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Soft-ICE User's Guide 

] 

By Nu-Mega Technologies P.O. Box 7780 Nashua, NH 03060-7780 (603) 889- 

T2386 

Copyright Nu-Mega Technologies @, 1987 - 1989. All rights reserved. No 
part of this publication or the enclosed software may be reproduced or 
distributed in any form or by any means without the prior written 
permission of Nu-Mega Technologies. It is permitted to make copies of the 
Soft-ICE diskette to be used solely for backup in case of destruction of 
the original. 

We welcome your suggestions and comments regarding improvements to Soft- 
UICE or this publication. Changes will be incorporated in new editions of 
this publication and in new versions of Soft-ICE software. Nu-Mega 
(Technologies reserves the right to make improvements of changes to this 
product at any time without notice. 

While every reasonable precaution has been taken in the preparation of 
this publication and software, Nu-Mega Technologies assumes no 
["■responsibility or liability of any kind for errors or omissions, or for 
the consequences of a such errors. The program is provided "as is" without 
warranty of any kind. The entire risk as to the quality and performance of 

Gthis program is to you. Should the program prove defective, you assume the 
entire cost of all necessary servicing, repair or correction. 
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The following trade names are referenced throughout this Manual 
IBM, PCDOS, Personal Series II, AT, MDA, CGA, 
EGA, and VGA are trademarks of International 
Business Machines Corporation. 
MSDOS, DEBUG, SYMDEB, CODEVIEW, 
Microsoft Windows, Ramdrive and Microsoft are 
trademarks of Microsoft Corporation. 

8086, 80286, 80386 and Intel are trademarks of Intel 

Corporation. 

CP/M is a trademark of Digital Research. 
Soft-ICE, MagicCV, and MagicCVW are 
trademarks of Nu-Mega Technologies. 
Compaq is a trademark of Compaq Computer 
Corporation. 
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Introduction 

1 . 1 Product Description 

1.2 Using This Manual 

1 . 3 System Requirements 



1.1 Product Description 



Soft-ICE is a software debugging tool that provides hardware-level 
''debugging capabilities to PCDOS and MSDOS debuggers. 

Soft-ICE uses 80386 protected mode to run DOS in a virtual machine. This 
gives Soft-ICE complete control of the DOS environment. Soft-ICE uses 
80386 protected mode features, such as paging, I/O privilege level, and 
break point registers, to add hardware-level break points your existing 
DOS debugger. 
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Soft-ICE was designed with three goals in mind: 

1. To utilize the 80386 virtual machine capability to 
debugging features that are impossible or 
prohibitively slow with software-only debuggers 
(e.g., real time hardware-level break points, 
memory protection, breaking out of hung 
programs , etc . ) . 

2 . To work with existing debuggers . We wanted to 
provide a tool that worked with existing tools. We 
designed Soft-ICE in such a way that you don't 
have to learn a new debugger to get powerful 
hardware debugging capabilities. 

3 . To be a user-friendly program with a window that 
pops up instantly and does not get in the way. All 
of the Soft-ICE commands were designed to fit in a 
small window so that information on the screen 
behind Soft-ICE could still be viewed. Dynamic 
on-line help assists users who only use Soft-ICE 

occasionally. 

i 

The Soft-ICE program features: 

* real time break points on memory reads/writes, 
port reads/writes, memory ranges, and interrupts 



* back trace history ranges 

* symbolic and source level debugging 

* an environment that works with existing debuggers 

* full EMM 4.0 support 

* backfilling to raise base memory past 640K for 

monochrome systems 

* a window that can pop up at any time 

* the ability to break out by keystroke even if 
interrupts are disabled 

* debugger code that is isolated by 80386 protected 
mode. This prevents an errant program from 
modifying or destroying Soft-ICE; even if DOS 
clobbered, Soft-ICE will still work 

* the ability to configure Soft-ICE to use no memory 
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in the lower 640K if the system has more than 64 OK 
user-friendly dynamic help 

the ability to be used as a stand-alone debugger. 

This ability is useful if you are debugging loadable 
device drivers, interrupt handlers, or boot 
sequences where traditional debugg 
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ers can't go, 

if your debugger suffers from re-entrancy problems 

* a soft boot capability that allows debugging with 
non-DOS operating systems or self-booting 
programs 

* a simple installation, with no DIP switches to set 
no I/O ports taken up, and no memory address 
space conflicts 

3 
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NOTE: 

Soft-ICE will work with real address mode programs 
only. It will not work with programs that use 8 0286 or 
80386 protected mode instructions. 



1.2 Using This Manual 



n 



e Soft-ICE manual is divided into four main sections: 
Learning Soft-ICE (Section I) 
Commands (Section II) 
Support Features (Section III) 
Advanced Topics (Section IV) 



Soft-ICE can be used for most debugging problems after reading Section I, 
"Learning Soft-ICE", and a little experimentation. Soft-ICE' s user- 

n friendly on-line help can be used to reference command descriptions and 
syntax. 



The "Learning Soft-ICE" section contains installation instructions, a 

G description of the user interface, and a tutorial. The tutorial is 
designed to get you up and running quickly. 
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The "Commands" section describes all of the Soft-ICE commands. The command 
descriptions are organized by functional group with an alphabetic index 
for reference. 



The "Support Features" section covers advanced loading options, symbolic 
and source level debugging, and EMM 4.0 capability. 



! 



The "Advanced Topics" section covers topics such as using Soft-ICE with 
DOS loadable drivers and using Soft-ICE with non-DOS operating systems. 
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Throughout the manual, 
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especially in the tutorial and the command section, 

examples are given that require you to give data to Soft-ICE. When the 
directions specify that you 



"press" a key, such as the key, you should press the key labelled . When 
the directions tell you to "enter" a phrase, such as WIN, you should type 
in the specified letters, then press the ENTER key. 

L 1.3 System Requirements 

Soft-ICE works with the IBM Series II Model 70 and 80, Compaq 80386 and 
1803 8 6SX computers, AT compatible and 8038 6 co-processor cards. Soft-ICE 
will only work with 80386 XT co-processors if they are AT compatible. 



Soft-ICE works best with extended memory, but works fine with conventional 
memory systems . 

Psoft-ICE does not use DOS or ROM BIOS for its video output and keystroke 
Uiriput. Therefore the video must be compatible with one of the following: 
MDA, Hercules, CGA, EGA, or VGA. Soft-ICE also has support for a two- 

D monitor configuration, which can be very helpful when debugging video- 
intensive programs. 
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SECTION I - - Learning Soft-ICE 
CHAPTER 2 

Getting Started 

2 . 1 The Diskettes 

2.2 Loading Soft-ICE 

2.2.1 Loading Without Extended Memory 

2.2.2 Loading With Extended Memory 

2.2.3 Configuring Soft-ICE for a Customized 

Installation 

2.3 Unloading Soft-ICE 

2.4 Reloading Soft-ICE 
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j2.1 The Diskettes 

Soft-ICE comes on either a 5 1/4" diskette or a 3 1/2" diskette. 



When you run Soft-ICE, the name of the person that your copy of Soft-ICE 
is licensed to is displayed on the screen as a deterrent to software 
pirates. The Soft-ICE diskette is not physically copy-protected for your 
convenience. For our convenience, we appreciate your high regard for our 
licensing agreement. It is important to make a duplicate copy to be used 
only for backup in case the original diskette is damaged. 

directory of a Soft-ICE diskette will show the following files: 
S-ICE.EXE 

OS-ICE. DAT 
LDR.EXE 
MSYM.EXE 
EMMSETUP.EXE 
UPTIME. EXE 
README. SI 
SAMPLE. EXE 
SAMPLE. ASM 
SAMPLE. SYM 
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S-ICE.EXE is the Soft-ICE program. 
jJs-ICE.DAT is the Soft-ICE initialization file. 
LDR.EXE is the Soft-ICE program and symbol file loader. 
MSYM.EXE is the Soft-ICE symbol file creation program. 

EMMSETUP.EXE is a program that allows you to customize the way your system 
will use expanded memory. 

UPTIME . EXE sets the time to that of the real time clock. 
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README. SI is a text file co 
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ntaining information about Soft-ICE that did 
not make it into this manual. 

SAMPLE . EXE is a short demonstration program that is used with the 
tutorial. 

SAMPLE. ASM is the assembly language source file for the demonstration 

program . 
SAMPLE. SYM is the symbol file for the demonstration program. 

S. 2 Loading Soft-ICE 
efore running Soft-ICE, copy all of the files on the distribution 
diskette to your hard disk. 

[jrhese files should be placed in a directory that is accessible through 
your alternate path list. 







S-ICE.EXE can be loaded as a device driver in CONFIG.SYS or can be run as 
a program from the command line. To use many of Soft-ICE 's features, S- 
ICE.EXE must be loaded as a device driver in CONFIG.SYS. 



or 



Note : 

If you do not have extended memory, Soft-ICE can NOT loaded as a device 
|_,river. Instead, it must be run from the DOS prompt. 

2.2.1 Loading Without Extended Memory 

When no extended memory is present, Soft-ICE loads it at the highest 
memory location possible. The memory used by Soft-ICE is then 'mapped 
out', making it invisible to DOS programs. Since the total memory visible 
j~jto DOS its programs is less after Soft-ICE loads, it is recommended 

9 

Dthat you load Soft-ICE before any TSR's or control programs. 
If you do not have extended memory, simply enter: 
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S-ICE 

2.2.2 Loading With Extended Memory 
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Loading Soft-ICE with extended memory can be done in one of two ways: 
1. Install S-ICE, EXE as a driver in CONFIG, SYS, 

This method is necessary if you will be using one 
the following capabilities: 

* Sharing memory with programs that use 
extended memory by using ROM BIOS calls 
(VDISK,SYS, RAMDRIVE . SYS , 
HIMEM.SYS, cache programs, etc.). 

* Using Soft-ICE' s EMM 4,0 capability, 

* Using Soft-ICE for symbolic or source level 
debugging. 

* Using back trace ranges. 

* Using Soft-ICE with other Nu-Mega products 
such as MagicCV, 

When loaded as a driver, Soft-ICE allocates a 
portion of extended memory for itself and its 
associated components so there can be no memory 
conflicts. S-ICE.EXE must be loaded in 
CONFIG.SYS before any other driver that 
allocates extended memory is loaded (e.g., 



VDISK.SYS, RAMDRIVE. SYS) . Generally 

Soft-ICE works best if it is the first loadable device 
driver installed in CONFIG.SYS. 

10 

For users that are new to Soft-ICE it is advisable to 
load Soft-ICE as the first driver in CONFIG.SYS 
with the following statement: 



de 



ice 



= drive: \path\S-ICE.EXE /SYM 50 
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Caution: 

When installing any new device driver for the first time on your system, 
it is advisable to have a boot diskette available This precautionary 
measure is for the unlikely event that The default setup of the device 
driver is not compatible with your system. 



Drive and path specify the directory where 
S-ICE.EXE is located. This statement will load 
Soft-ICE at system initialization and will be 
adequate for the tutorial. However, Soft-ICE will 
not be installed for some of its more powerful 
features such as EMM 4.0. You can reconfigure 
Soft-ICE with those features enabled after you 
have experimented a bit. If you already have 
experience with Soft-ICE or would like to set up 
Soft-ICE with those features immediately, please 
read chapter 6 (Soft-ICE Initialization Options) . 
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If you are not sure how to edit your CONFIG.SYS 
file, refer to your system user's guide or your text 
editor user's guide for instructions. After you have 
modified your CONFIG.SYS file, you must reboot 
your system to have the changes take effect. 

2. Run Soft-ICE from the DOS Prompt by typing 
S-ICE. Before actually loading, Soft-ICE will 
display a loading message and prompt. To prevent 
this prompt, place the word EXTENDED in the 
S-ICE. DAT file. See section 6.4 for more 
information on the S-ICE. DAT file. Using this 

11 

method, S-ICE.EXE is automatically loaded into 
the top of extended memory, whether or not 
anything else is already there. If you know you will 
not have any other programs using extended 
memory, this method is acceptable. When loaded 
with this method, Soft-ICE occupies ZERO bytes 
of conventional memory. The command you use is: 

S-ICE 

Notes: 

5fou can NOT enable all of Soft-ICE' s features when Loading from the 

ommand line. If you will be using Soft-ICE as a stand-alone debugger, it 
is recommended to Load Soft-ICE from CONFIG.SYS. 



•If you want to load Soft-ICE as a device driver, but don't want Soft-ICE 
to be resident all of the time, you should use the /UN loading switch. 
Refer to section 6.3.1 for more information. 



2.2.3 Configuring Soft-ICE for a Customized Installation 



4fou can customize Soft-ICE with Soft-ICE loading switches in CONFIG.SYS 
and with the Soft-ICE initialization file S-ICE. DAT. The CONFIG.SYS 



loading switches allow you to customize how the extended memory will be 
reserved by Soft-ICE. The initialization file S-ICE. DAT alio 
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ws you to 

specify configuration options, assign commands to function keys, and 

C 'define an auto-start string. An auto-start string is used to execute a 
series of commands that you use every time you install Soft-ICE. for more 
information about customizing Soft-ICE, refer to chapter 6. 

D » 

p. 2.3 Unloading Soft-ICE 

^-Occasionally you may need to unload Soft-ICE. A typical reason for 

unloading Soft-ICE is to run a program that uses 802 86 or 803 8 6 protected 
Qnode instructions. To unload Soft-ICE, enter: 

S-ICE /U 

JThis command places the machine back in real address mode. If Soft-ICE was 
initially loaded from CONFIG.SYS When the memory is still reserved for 
Soft-ICE and can not be used by other software. If Soft-ICE was initially 
loaded from the command line, unloading frees up the memory consumed by S- 
ICE.EXE. 

paution: 

;If you have any backfilled memory in your system, or if expanded memory is 
currently being used, unloading Soft-ICE could crash your system. 

J 2.4 Reloading Soft-ICE 

Soft-ICE can be re-loaded at any time even if it had initially been loaded 
~|in CONFIG.SYS. If Soft-ICE had initially been loaded in CONFIG.SYS then 
the original configuration opti 
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Oris (EMM 4.0, symbols and source...) are 
still in effect. To reload Soft-ICE, enter 

S-ICE 
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CHAPTER 3 

Debugging In 3 Minutes 

3 . 1 Introduction 

3 . 2 Popping Up the Window 

3 . 3 Returning From the Window 

3 . 4 Changing the Window Size 

3 . 5 Moving the Window 

3 . 6 Line Editing Keystrokes 

3.7 Interactive Status Line 

3 . 8 Command Syntax 

3.8.1 Specifying Memory Addresses 

3 . 9 Function Keys 

3.10 Help 

3.11 Tutorial 
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3 . 1 Introduction 



All interaction with Soft-ICE takes place through a window that can be 
popped up at any time. All Soft-ICE commands fit in a small window, but 
"the window can be enlarged to full screen. You will typically use the 
small window when using Soft-ICE as an assistant to another debugger, and 
the large window when using Soft-ICE in stand-alone mode. 

The window initially comes up in full screen mode if you are using the 
■Soft-ICE configuration file (S-ICE DAT) that was included on the 
distribution diskette. 
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3 . 2 Popping Up the Window 



You can bring up the window at any time after installing Soft-ICE. You 
initially bring up Soft-ICE by pressing the CTRL and D keys. However, this 
sequence can be changed by using the ALTKEY command (see section 5.8). 



D 



3.3 Returning From the Window 



Return to the original display by using the X command or the key sequence 
that you used to invoke Soft-ICE. Any break points that you set while 
^working in Soft-ICE will be armed at this point. 

3.4 Changing the Window Size 

^You can modify both the width and the height of the Soft-ICE window. 
Changing the window size is particularly useful in stand-alone mode when 

you are displaying code memory. 

i 
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The window height can vary from 8 to 2 5 lines tall. To change the window 
height, use the following key sequences: 



ALT — makes the window taller 
ALT — makes the window shorter 



(To change the window width, use the WIN command (see section 5.9). 
.Entering WIN with no parameters toggles between the following two modes: 



WIDE mode — full screen width 



NARROW mode — 4 6 characters wide 
Borne commands (i.e., D, E, R, U) take advantage of the e 
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xtra width by 

displaying more information when the window is in wide mode, 
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3 . 5 Moving the Window 



ClFhe Soft-ICE window is movable and can be positioned anywhere on the 
screen. This is particularly useful when the window is in narrow mode. 
Move the window anytime you need to view information on the screen behind 
the window. The following key sequences move the window: 
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CTRL — moves the window one row up 

CTRL — moves the window one row down 

CTRL — moves the window one column right 

CTRL — moves the window one column left 



. 6 Line Editing Keystrokes 



U 



Soft-ICE 's easy-to-use line editor allows you to recall and edit previous 

C commands. The line editor functions are similar to those of the popular 
2ED line editor. The 
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following key sequences help you edit commands in the command window: 



a 

D 

□ 
D 
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D 
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D 








D 
D 
D 

a 



J — moves the cursor to the right 

— moves the cursor to the left 
INS — toggles insert mode 
DEL — deletes the current character 
HOME — moves the cursor to start of the line 
END — moves the cursor to the end of the line 

— displays the previous command 

— displays the next command 
SHIFT — scroll one line up in display 
SHIFT — scroll one line down in display 
PAGE UP — scroll one page up in display 
PAGE DN — scroll one page down in display 
BKSP — deletes the previous character 
ESC — cancels the current command 



There are special key assignments when the cursor is in the data window or 
the code window. These are described in the sections for the E and EC 
command respectively. One special assignment of note is the SHIFT and 
Shift keys while the cursor is in the code window. These keys are re- 
assigned so they have the functions that and normally have. This way 
you can recall previous commands while the cursor is in the code window. 
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3 . 7 Interactive Status Line 



A status line at the bottom of the window provides interactive help with 
command syntax. 
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3 . 8 Command Syntax 




D 

Soft-ICE is a command-driven debugging tool. To interact with Soft-ICE, 
|-you enter commands, which can optionally be modified by parameters. 

All commands are text strings that are one to six characters in length and 
pre case insensitive. All parameters are either ASCII strings or 
^expressions . 

Expressions are typically numbers, but can also be combinations of numbers 
and operators (e.g., + - /*). All numbers are displayed in hexadecimal 
format. Byte parameters are 2 digits long, word parameters are 4, and 
double word parameters are 2 word parameters separated by a colon 
Here are some examples of parameters: 
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12 — byte parameter 

10FF — word parameter 

E000:0100 — double word parameter 



Registers can be used in place of bytes or words in an expression. For 
example, the command 'U CS:IP-10' will start unassembling instructions ten 
bytes before the current instruction pointer address. The following 
register name may be used in an expression: 



j 
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AL, AH, AX, BL, BH, BX, CL, CH, CX, DL, DH, 
DX, DI, SI, BP, SP, IP, CS, DS, ES, SS, or FL 

3.8.1 Specifying Memory Addresses 



Many Soft-ICE commands require memory addresses as parameters. A memory 
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address is a value that is made of two 16-bit words, separated by a colon 
The first word is the segment address, and the second word is the segment 
offset. 
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Public symbols can be used in place of an address in any Soft-ICE command, 
The public symbols must have been loaded with the Soft-ICE program loader 
p,(LDR. EXE) . See chapter 7 (Symbols and Source) for a complete description 
of using public symbols. 
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The Soft-ICE expression evaluator recognizes several special characters in 
conjunction with addresses. These special characters are: 



$ — Current CS:IP. 

©address — Double Word Indirection 

.number — Source Line Number 



.The $ character can be used in place of CS:IP when typing the address of 
the current instruction pointer. 

The @ character allows you to refer to the double word pointed to by the 
"address. You can have multiple levels of @'s. 

If the . character precedes an address, the address will be interpreted as 
r~fL source line number in the current file, rather than an actual address. 

This is only valid when source files are loaded. The address is 
interpreted as a decimal number in this case. 

C Examples: 
U. 1234 

This command starts unassembling instructions at 
source line 1234 decimal. 
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Function keys can be assigned to any command string that can be typed into 
Soft-ICE. Function keys can be assigned from the command line or pre- 
initialized throu 



U $-10 

This command unassembles instructions starting 10 
bytes prior to the current instruction pointer. 

20 

G @SS:SF 

Assume you are at the first instruction of an interrupt 
routine. Entering this command will set a temporary 
break point at the return address on the stack and skip 
the interrupt routine. 

3.9 Function Keys 



) 
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gh the Soft-ICE definition file S-ICE.DAT. 



JjThe default S-ICE.DAT that comes on the Soft-ICE distribution diskette has 
Ldefinitions for all 12 function keys. You can change any of these 

definitions at any time. They are intended as examples, but they are 
redesigned to make easy for users of Microsoft's CodeView, Thee default 

assignments are: 
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Fl — Displays general help (H;) 

F2 — Toggles the register window ( A WR;) 

F3 — Changes current source mode ( A SRC;) 

F4 — Restores screen ( "RS;) 

F5 — Returns to your program ( A X;) 

F6 — Toggles cursor between command window 

code window ( *EC;) 
F7 — Goes to current cursor line ( A HERE;) 
F8 — Single steps ( A T;) 

F9 — Sets break point at current cursor line ( A BPX;) 
21 



□F10 — Program steps ( A P;) 
Fll — Go to return address (large model) 
( A G@SS:SP;) 

□F12 — Displays Soft-ICE version number ( A VER;) 
A caret ( A ) preceding a command makes it invisible, a semi-colon (;) 
following a command represents a carriage return. You can display the 
j~jcurrent function key assignments by entering the command: 

FKEY 

Rro use a function key simply press the function key instead of entering 
the command. To program function keys see section 5.8 for a description of 
the FKEY command, or chapter 6 for a description of pre-initializing 
•function keys in S-ICE.DAT. 

3.10 Help 

The help command displays a short description, a syntax expression, and an 
example of each command. To display help information, enter: 
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? or H — displays short descriptions of all 

commands and operators 

? command or 

H command — displays more detailed information on 

the specified command, syntax, and an 
example 

? expression or 

H expression — displays the value of the expression in 

hexadecimal, decimal and ASCII 

22 

3.11 Tutorial 



line following tutorial demonstrates a few of the features Soft-ICE and 
gives you the opportunity to try using Soft-ICE. Soft-ICE can be used in 
conjunction with another debugger or as a stand-alone debugger. The 



D 



tutorial demonstrates using Soft-ICE as an assistant to the DOS debugger, 
DEBUG, and then shows how Soft-ICE can be used as a stand-alone debugger 

Dwith source and symbols loaded. DEBUG can be found on the PCDOS or MSDOS 
ystem diskette. If you do not have DEBUG, you can use another debugger in 
its place, or Soft-ICE can be used as a stand-alone debugger. 

Qjsers who need to use Soft-ICE for a reverse engineering project, or for 
debugging DOS loadable device drivers or Terminate and Stay Resident 
programs should go through this tutorial too. Even though examples of 
J these types of programs are not demonstrated directly, you will get an 
L-overview of debugging with Soft-ICE. It is recommended that you experiment 
with Soft-ICE and your particular environment before beginning a real 

□project. 

A short assembly language program with a subtle flaw is used to 
demonstrate hardware-style break points. The sample program has been kept 
'intentionally short and to-the-point for those not very familiar with 

ssembly language. The tutorial is designed to give you a peek at Soft-ICE 
features. Feel free to experiment on your own after going through the 
jjtutorial. 

Since Soft-ICE is very flexible, it allows you to load in the way that is 
rbest for your system. Go through the installation procedures in section 
IJ2.2 before continuing with the tutorial. 

Clf you do not have extended memory on your system, you must load Soft-ICE 
jfrom the command line. When loading Soft-ICE from the command line you can 
not load symbols or source files. In this case you must improvise in the 
last 



D 
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i section of the tutorial where Soft-ICE is used as a stand-alone debugger. 



Soft-ICE can be loaded from the DOS prompt or loaded as a device driver in 
CONFIG.SYS. For the purpose of this tutorial you should install Soft-ICE 
Hin CONFIG.SYS with at least 50K of extended memory reserved for symbols 
Land source files. Soft-ICE should be the first device driver installed in 
CONFIG.SYS. The device installation line should look like: 



D 



DEVICE = drive: path\S -ICE. EXE /SYM 50 



The /SYM 50 parameter instructs Soft-ICE to reserve 50 kilobytes of 
extended memory for symbols and source file This is not enough to solve 
•-most real world problems, but will work for our sample program. 

jjYou must re-boot your system after placing this line in CONFIG.SYS. 

When you re-boot your system Soft-ICE displays a copyright notice, a 
^registration number, the name of the person who owns this copy of Soft- 
Mi CE, and the amount a extended memory reserved for each Soft-ICE 
component. On a system with 3 84K of extended memory the initial screen 
looks like: 
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Soft-ICE Your Name Your Company Name Registration # SInnnnnn 
Copr. (C) Nu-Mega Technologies 1987-1989 All Rights Reserved Soft-ICE 
Version 2.00 Soft-ICE is loaded from 00132000H up to 00160000H. 50K of 
symbol space reserved. 10K of back trace space reserved. 200 K of extended 
memory available. 



D 
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1 The "Soft-ICE is loaded ..." message tells you the exact area of memory 
Lthat Soft-ICE and its components are occupying. If you are on a Compaq or 
Compaq clone and have included the word COMPAQ in your S-ICE.DAT file you 
rfould also see a message saying "Using high memory from XXXXXXXX to 



00FE00OOH" . 



[ 



.The next line tells you how much symbol space has been reserved. This 
space is used for both symbols and source files. 



The next line tells you how much memory has been reserved for back trace 
'history. This amount defaults to 10K. This memory area is used by the SNAP 
fcommand and the BPR command with the T or TW options. 



[ 
1 



The last line tells you how much memory is left for regular extended 
memory. This memory can be used by other programs, such as HIMEM, 
SMARTDRIVE, VDISK, etc. 



Change directories to the hard drive directory where you loaded all the 
iles from your distribution diskette. Remember, this directory must be 
accessible from your alternate path list. 



D 



: 



Before we get into heavy debugging, let's bring the Soft-ICE window up and 
give it a test drive. 

Clear the screen by entering: 
CLS 

Bring up the Soft-ICE window by pressing: 
CTRL D 



The Soft-ICE window is now on the screen. If you have file S-ICE.DAT 
accessible from your path then the Soft-ICE window will occupy the entire 
(-screen. It will be divided into four sections. From top to bottom, these 
[^sections are the register window, the data window, the code 
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L-window, and the command window. If S-ICE.DAT was not found then you will 
have a small window in the center of the screen. This also means that 
other components needed for the tutorial have not been loaded. 



D 
D 



If the small window is visible you should: 

1. Exit from Soft-ICE by entering X. 

2. Unload Soft-ICE by entering S-ICE /U. 

3. Copy the file S-ICE.DAT from the distribution 
diskette to a directory accessible from your current 
path. 

4 . Restart the demo . 



We will now switch to the small window. The small window is very 
convenient for using Soft-ICE as an assistant to another debugger. 



a 



Enter: 
WIN 




D 



This will make a small command window in the center of the screen. Several 
feoft-ICE commands are visible on t 



Q 



his screen. These are remnants of the 
initialization string in S-ICE.DAT that originally set up Soft-ICE in the 
jjfull screen mode. 

You will notice a prompt symbol (:) and a status line at the bottom of the 
indow. 



D 
D 
D 



The Soft-ICE window can be moved around on the screen, and the window size 
an be adjusted. 



Move the window around the screen by pressing: 
CTRL — moves the window up one row 
CTRL — moves the window down one row 
CTRL — moves the window one column left 
CTRL — moves the window one column right 
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Change the window size so that it fills the whole screen 
by entering: 
WIN 



Jfou will notice that the original screen is back. 

Change back to the small window by entering WIN 
again. 

Make the window taller or shorter by pressing: 



ALT — makes the window taller 
ALT — makes the window shorter 



D 
D 

Now try what comes naturally when you're in front of a new program and you 
j-jdon't have the foggiest notion of what to do next — ask for help. 

Get a help display by entering: 
7 

Qlotice how the display stops and waits for a keystroke before scrolling 
any information off the screen. Look at the status line at the bottom of 
the window. The status line displays the instructions: "Any Key To 
Continue, ESC to Cancel ". Now press any key to continue displaying more 
the help information. Continue pressing the key until the prompt (: ) 
reappears. 

Scroll back through the help information by pressing 
SHIFT 



D 



Previously displayed information in the command window can be scrolled 
with the shift up, shift down, page up and page down keys. Try a variety 
'of these keys to scroll through the help information. 
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The Soft-ICE help facility gives you an overview of each command. If you 
L 'enter a question mark (?) followed by a command name, you see a display 
showing the command syntax, a short description of the command, and an 

|~jexample. 

Try experimenting with help by entering commands in 
this format: 



D 



D 



D 



? command 
For example, 
? ALTKEY 



□ 



Pay attention to the status line prompts on the bottom line of the screen 
if you get confused. 



The help command also allows you to evaluate hexadecimal expressions. 



a 
a 

a 



For example, enter: 
? 10*2+42 

The resulting display shows you the value of the 
expression, first in hexadecimal, then decimal, then in 
ASCII representation: 
0062 00098 "b" 

e brought up the window with the CTRL D key sequence. That's all right 
or some, but you may prefer to use another key sequence. 



□ 

D 
D 
D 



We are now going to enter a command to change the key sequence required to 
bring up the window. We'll do this one step at a time, so you can get used 
ito the status line at the bottom of the window. 



D 
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Type the letter 'A' . The status line displays a list of all 
the commands starting with the letter 'A' . Finish 
typing the word 'ALTKEY' . The status line now 
displays a short description of the /ALTKEY command 
Press the space bar. The status line now shows the 
required syntax for the / ALTKEY command. Type the 
letters 'ALT D' then press ENTER to enter the entire 
command : 

ALTKEY ALTD 



D 



You just changed the window pop up key sequence to ALT D. From now on, you 
must press the ALT D key sequence to pop up the window. This is assumed 
throughout the remainder of the tutorial. 
Now let's test the previous command. 



D 

r 





To exit from the window, press: 
ALT D 



The Soft-ICE window just disappeared. 

To return to the Soft-ICE window, release the ALT 
key, then press: 
ALT D 



D 



The window returned. 

To see some previous commands, press: 
the key a few times. 
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Hot ice that Soft-ICE remembers commands that have been entered. Try 
editing one just for fun. Some of the editing keys are: 



D 



D 
D 
D 



INS — Toggles insert mode on or off 
DEL — Deletes one character 
HOME — Moves the cursor to start of line 
END — Moves the cursor to end of line 

— Moves the cursor one column to the right 

— Moves the cursor one column to the left 



When insert mode is on, notice that the cursor is in a block shape. 

Now that you are somewhat familiar with the environment let's try some 
more commands. 



D 
D 

D 



Erase the command you were editing by pressing the 
HOME key, then pressing the DEL key until the 
command is gone. 

Enter : 

WR 



The WR command makes the register window visible. The register window 
displays the contents of the 8086 registers. Notice that the register 
values reflect the location where the code was executing when you invoked 
QSoft-ICE. 

The WR command is assigned to the function key F2 in the Soft-ICE 
initialization file S-ICE.DAT. 



D 
D 
D 
D 



Press the F2 key several times and you will see the 
register window toggle on and off. Leave the register 
window visible. 
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Extend the vertical size of the Soft-ICE window by 
holding down the ALT and the until the window is 
the entire length of the screen. 

Notice the values of the CS and IP registers in the 

register window, then enter: 



MAP 

The MAP command displays a system memory map. The area of the current 
[-^instruction pointer (CS:IP) is highlighted. If you have a complex memory 
map you may have to press a key a few times until the until the prompt 
reappears. 







Now try the following sequence a few times, noticing 
the (CS:IP) registers in the register window. 
ALT D 

Release ALT and D 
ALT D 



Each time you bring the Soft-ICE window back up you will notice that the 
CS and IP registers have changed. When CS and IP change you can enter the 
MAP command again to see if the instruction pointer now points to a 
different area. 



: 



This little exercise demonstrates that Soft-ICE is a system level debugger 
that pops up wherever the instruction pointer happens to be when you press 
jjthe Soft-ICE hot key sequence. The instruction pointer is continuously 



Q 



changing because there is a lot of activity happening behind the scenes 
even when you are at the DOS prompt, such as timer interrupts, DOS device 
|~jdriver polling, DOS busy waiting other interrupts, etc. 
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D 



Press the F12 function key 



pThe F12 function key defaults to be assigned to the Soft-ICE VER command, 
jit displays the Soft-ICE copyright message and the version number. 
We will now assign the F12 function key to the Soft-ICE RS command. 



D 



Enter 
RS 







D 



This will temporarily show the program screen without the Soft-ICE window. 
Press the space bar to get back to get back the Soft-ICE 
window. 
Enter: 

FKEY F12 RS; 



This assigns the RS command to the F12 key. The semi-colon represents the 
RENTER key. 

Press the F12 key. 



d 



Repeat this a few times to toggle between the Soft-ICE window and the 
program screen. Now make sure the Soft-ICE window is displayed, by 
pressing the F12 key if necessary. You will notice RS displayed several 
times in the window. There is one occurrence for each time you pressed the 
jjF12 key to show the program screen. 

Clear the Soft-ICE window by entering: 
CLS 



n 
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Enter : 

FKEY F12 A RS; 



Press the F12 key several times. Notice that the RS 
command no longer displays in the Soft-ICE window. 



The A symbol is a shifted 6. This assigns the RS command to the F12 key, 
but makes it an invisible command. 

J 

D 

You can also assign a sequence of Soft-ICE commands to a function key. 
Remember to place a carriage return between each command. 
LNow let's prepare to use Soft-ICE as an assistant to the MSDOS DEBUG 
utility. 




D 



Get rid of the register window by pressing the F2 . 
then shrink the window size down to about 6 lines by 
Using ALT . 
Enter: 

ACTION INT3 



DThis command tells Soft-ICE to generate interrupt 3's when break point 
conditions are met. That's how Soft-ICE will communicate with DEBUG. The 
default setting is HERE. ACTION HERE will cause control to return directly 
o Soft-ICE. Use ACTION HERE when using Soft-ICE as a stand-alone 



[f 



debugger. 



□For those of you not using DEBUG with this tutorial you might have to 
improvise now. CODEVIEW works with ACTION set to NMI. Most other debugger 
will work with ACTION set to INT3 . If your debugger doesn't, and you need 
rhelp improvising, refer to the complete description ACTION (see section 



D 
D 
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To make the Soft-ICE window disappear again, enter: 
X 



(This is an alternative method to exit from Soft-ICE. This especially 
useful in function key definitions. 

Now that you are familiar with some of the basics of using Soft-ICE, let' 
learn some details by debugging the sample program (SAMPLE. ASM) . 

Ps AMPLE . ASM is a simple program written in assembly language by a 
L-4>rogrammer named Jed. The program reads a keystroke from DOS and displays 
a message telling whether the keystroke was a space. 



D 



To run the program SAMPLE, enter: 
SAMPLE 



Now press the space bar. Press several keys. Jed's program obviously has 
•—problem! Jed has spent hours studying this source code and is certain 
there are no flaws in his logic. However, Jed borrowed some 'helper' 

G routines from his friend Jake (get_key, is_space?) . Jed is somewhat 
uspect these routines but he cannot find the bug. 



1 
□ 

D 

D 
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he source code for Jed's program looks like this: 



Page 55,80 

Title Sample program for Soft-ICE tutorial 
DATA Segment Public 'Data' 
pad db 12H dup(O) 

char db 
answer db 

space_msg db 'The Character is a SPACE' , ODH, OAH, '$ ' 
no_space_msg db 'The Character is NOT a' 
db 'SPACE' , ODH, OAH, '$' 

DATA Ends 

STACK Segment Stack 'Stack' 

Dw 128 Dup (?) /Program stack STACK Ends 

CODE Segment Public 'Code' 
"I Assume CS : CODE , DS: DATA, ES: Nothing, SS: STACK 



start: 

n 



D 



; Set up segments 
mov ax, DATA 
mov es,ax 
mov ds,ax 

Main Program Loop 



D 



D 



D 

0; 



main, loop: 

call get_key 
call is_space? 
cmp answer, 
je no, space 
It's a space, so display the space message 
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mov ah , 9 

mov dx, offset space_msg 
int 21H 
jmp main_loop 
It's NOT a space, so display the no space message 



a 



no_space : 
mov ah , 9 

mov dx, offset no_space_msg 
int 21H 
jmp main loop 



JAKE'S ROUTINES 



C; Get Key Routine (one of Jake's routines) 
get_key proc 
mov ah , 8 
int 21H 



D 




D 
D 



mov char,al 
ret get_key endp 

; Check if character is a space (one of Jake's routines) 



is_space? proc 
cmp char ,2 OH 
jne not_space 
mov answer, 1 
ret not_space : 
mov cs : answer, 
ret is_space? endp 



CODE Ends 
Endstart 



U 
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Ljed has been using DEBUG but has not been able to pinpoint the problem. As 

a recommendation from his nephew Jethro, Jed has purchased Soft-ICE. He 
["Was somewhat reluctant to use it because he had tried a hardware-assisted 
Udebugger but could never get it working quite right. He was willing to try 
Soft-ICE because he could continue to use DEBUG — the only debugger he 
really understood. 



U 

D 

D 



Press CTRL C to break out of the program. 
Enter the following commands: 

DEBUG drive: \ pathname \ SAMPLE. EXE 

U 

R 







In the hours Jed has spent trying to find this elusive bug, he has had the 
suspicion that something is overwriting his code in some subtle way. With 
jjSoft-ICE, Jed decides to set a range break point across his code segment. 

Press: 
ALT D 



D 



D 



The Soft-ICE window is back. Move the window (by using 
CTRL and the arrow keys) until DEBUG 's register 
display is visible. It's time to set our first break point. 



D 



Enter : 

BPR code-seg:0 code-seg:25 W 



it 



Code-seg is the value in the CS register as displayed by the 
EBUG R command. 



he BPR command sets a memory-range break point. The length of Jed's code 

C segment is 25H bytes, so the memory range specified goes from the 
beginning of his code segment to the end. The W tells Soft-ICE to break 
on a write. We want to catch any unexpected writes to Jed's code. 
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Enter: 
BL 



D 
D 

The BL command displays all break points. The display from BL looks 
|~jsimilar to the following display: 

0) BPR code-seg: 0000 code-seg: 0025 W C = 01 

The is the identifier for this break point. The range and W are 
displayed as they were entered, and the count (since none was specified) 
defaults to one. 



[I 

i 



Now comes the moment of truth. 
Press ALT D. 

Qrhe window disappears again. 

To run SAMPLE from DEBUG, enter: 
G 

Press the space bar. Ok so far. Now press a non-space 
key. 



□ 



Our break point just woke up DEBUG. The registers and single unassembled 
instruction are displayed. 



D 



Enter: 

U cs: address 



Address is the value of the IP register minus 10 hexadecimal. Since DEBUG 
as rather primitive, the value of the IP register minus 10 hexadecimal 
must be calculated by hand. The instruction pointer is pointing one 
instruction past the instruction that caused the break point. By going 
jjback ten hexadecimal instructions, DEBUG should sync up. 
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D 



The instruction at offset 3BH is: 
CS: 

MOV BYTE PTR [13] ,0 



Jed says,"There it isi I just knew Jake's helper routines were the 
problem! His code segment override instruction is writing a zero byte 
right over my code! Who knows what that's doing!" 



D 



Enter : 
U 



Location 13H happens to be the offset of a conditional jump instruction. 
The relative offset of the conditional jump is being set to zero. If you 
are an 808 6 guru, you obviously know that the JE will ALWAYS fall through 
if the relative offset is zero. What a subtle BUG! 

n 

Now we will take a quick look at how this problem would be solved using 
Soft-ICE as a stand-alone debugger. But first we must exit from debug. 



G 



Before exiting the debugger, it's always a good idea to disable all the 
break points, unless ACTION is set to HERE. If you do not do this, when a 
break point occurs and ACTION tries to return to a debugger that is not 

C loaded, the results are unpredictable. We've changed the ACTION to INT3 , 
so we have to disable the break point. 



D 
D 



To bring up the window, press: 
ALT D 

List the break point by entering: 
BL 
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P 

iNotice that the break point description line is highlighted. The 
highlighted break point is the last break point that occurred. 



D 



Notice that the break point number is 0. To disable 
break point zero, enter: 
BD 

List the break point again by entering: 
BL 



D 
D 



The asterisk (*) after the break point number shows that the break point 
is disabled. 



To clear the break point, enter: 
BC 
Enter BL again. 



QNotice that there are no break point lines displayed. 

Exit from Soft-ICE, then exit from the debugger, by 
entering: 

X 
Q 



D 



1 The next part of the tutorial demonstrates how Soft-ICE can be used to 
find the same problem as a stand-alone debugger. Soft-ICE will be used as 
a source level debugger. 



D 



D 



To prepare Soft-ICE to debug at source level it must have been installed 
in your CONFIG.SYS file, and extended memory allocated for symbols and 

D source files. Soft-ICE can only be used as a source level debugger if you 
nave extended memory on your system. If you do not have 
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extended memory you may still want to read through the rest of the 

C [tutorial to see the capabilities of Soft-ICE with extended memory. If you 
have not loaded S-ICE.EXE in your CONFIG.SYS file with memory reserved for 
symbols, do so at this time. 

CjTo debug the sample program with Soft-ICE as a stand-alone debugger we 
must use the Soft-ICE program loader (LDR.EXE) . To load the sample 
program (SAMPLE. EXE) , the symbol file (SAMPLE. SYM) and the source 
file (SAMPLE. ASM) enter: 



LDR SAMPLE 



[~jYou are now in Soft-ICE with SAMPLE . EXE loaded into memory. Notice that 
Lsoft-ICE occupies the full screen. Soft-ICE switches to its wide mode 
whenever a program loaded. The source from SAMPLE. ASM should be visible in 

Dthe code window. In addition, the register window and the DATA windows are 
visible. 



1 



Step through one instruction by pressing F10. 



D 
[f 

D 



otice that the reverse video bar moves to the next instruction to be 
executed after a program step. 



Press F6. 

his places the cursor in the code window. 
Now experiment with the , , pageUp, and 
pageDn keys to move the cursor and scroll the 
source file. 

Move the cursor down to line 4 2 with the key. 
41 
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D, 



Press F9. 

We have just set an execution break point on line 42. The line should be 
highlighted, showing you that a break point has been set on it. 



Enter: 

BL 

his shows the break point that we have just set. 
Now press ALT D. 



This exits Soft-ICE, and causes the sample program to execute until it 
encounters the break point on line 42. Soft-ICE should immediately come 



back, with the reverse video bar on line 42. 
Press F6 again. 



Rrhis will bring the cursor back to the command window. Now enter: 
U BC * 



'his will clear all the break points (there should only be one set) . 



Now exit from Soft-ICE by pressing ALT D. 



Gifou are back to the sample program. Type a few keys just to make sure it 
is still broken. 

Now pop Soft-ICE back up with ALT D. 



D 



Since the bug has already occurred, we want to restart the program. Enter 
EXIT RD 
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This command forces the sample program to exit. The R tells Soft-ICE to 

D restore the interrupt vectors to the state they were when the sample 
program was loaded with LDR. The D tells Soft-ICE to delete any currently 
pending break points. The R and the D are not necessary in this ca 



D 
D 

D 
D 
D 
D 

D 



D 
D 
D 
D 
D 
□ 



se, but 

it is good to get in the habit of specifying them when exiting a program 
that was loaded with LDR.EXE. 

You are now back at the DOS prompt. Reload the 
program by entering: 



D 



LDR SAMPLE. EXE 



Notice the suffix.EXE was specified this time. When the suffix is 

pecified, Soft-ICE does not attempt to load a symbol file or source file. 
In this case the symbol file and source file are already in memory. 



D 



Enter : 
SYM 



This displays the public symbols of the sample program. 
Press Esc to get back to the prompt. 

We will now set a range break point similar to the one we set while using 
L'soft-ICE as an assistant to debug. This time we will use symbols to set 
the break point. Enter: 



D 



BPR START .82 W 



This will set a range break point in our code segment from the symbol 
START to line 82 of the source file. 



D 



Enter: 
BL 



You can verify that the break point has been set properly. 
43 



Press ALT D. 

Press a non-space key. 



D 
D 

We're back in Soft-ICE. Notice that the current instruction (the line with 
the reverse video bar) is the instruction after the one that caused the 
break point. 

To see the actual code press the F3 key. 

This places Soft-ICE in mixed mode. Notice that the reverse video bar 
covers 2 lines. This is the actual code line and the source code line of 
jjthe current instruction. 



D 



Press the F3 key again. 



We are now in code mode. No source lines are visible. The instruction 
above the reverse video bar is the instruction that caused the range break 
point to go off. 

Press the F3 key again to get back to source mode. 



D 



Now we will fix the bug in the sample program. 
Exit the sample program and go back to the DOS 
prompt by entering: 



D 
D 
D 



D 



EXIT RD 

Re-load the sample program by entering: 
LDR SAMPLE. EXE 

Set the code window in code mode by pressing the 
F3 key twice. 

Un-assemble at the broken routine by entering: 
U not_space 
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We will now use the Soft-ICE interactive assembler to fix the problem. 



Enter : 

A not_space 



D 



Soft-ICE will prompt you with the address. 
Enter: 
NOP 

Press ENTER to exit from the assembler. 



Notice in the code window that there is a NOP instruction in place of the 
CS over-ride at offset 003BH. 



D 
D 



Press the F3 key to get back to source mode, (the 
source code of course is not modified) . 
Press ALT D to run the mended sample program. 

Enter : 

spaces and some non-spaces 



D 



It works! You fixed the bug I 

To get out of Jed's program, and return to DOS, press: 
CTRL C 



Now we're going to demonstrate another feature of Soft-ICE 



D 



Enter : 

LDR SAMPLE. EXE 



This will load the sample program in one more time. 
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Enter : 

RIP HANG EXAMPLE 



Li 



[ 



The first two displayed instructions are: 
CLI 
JMP $ 



D 
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Notice that the jump instruction jumps to itself. This infinite loop would 
normally hang the system in an unrecoverable fashion. 



Enter: 

BREAK ON 



We have just turned on BREAK mode. BREAK mode will cause the system to run 
slightly slower, but will allow Soft-ICE to come up even when the system 
jjwould normal be hung. 



D 
D 

D 



Exit from Soft-ICE by pressing ALT D. 

Your system is now hung. For those non-believers, press: 
CTRL ALT DEL 

Nothing happens! It is definitely hung. 
Now press ALT D. 



he Soft-ICE window is back! 

To get out of the infinite loop, enter: 
EXIT RD 



EYou are now back at DOS. Try a few directories to get a feel for the 
performance degradation. Many people feel comfortable leaving BREAK ON as 
a configuration default. 



D 

D 
□ 
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Turn BREAK mode off again by entering: 
ALT D 
BREAK OFF 
ALT D 



Do a few directories to get a comparison of the speed. 
That's itl Have fun! It's time to start experimenting and debugging on 

Cyour own. Browse through the rest of the manual and refer to specific 
sections when necessary. 



D 
D 
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Blank 
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SECTION II — Commands 
Section II contains syntax listings for each Soft-ICE command, and 



section 11 contains syntax listings ror eacn boit-ita command 
explanations and examples for each command. All numbers are in 
hexadecimal; any number can be an expression using +,-,/,*, or registers. 
All commands are case-insensitive. Words that are in italics the command 
syntax statements must be replaced by an actual value, rather than typing 
in the italicized word. 



d 



The following notational conventions are used throughout this section: 
[ ] — Brackets enclose an optional syntax item. 
< > — Angle brackets enclose a list of items 

or choices. 

x | y — Vertical bars separate alternatives. 

Use either item x or item y. 
count — Count is a byte value that specifies the 

number of times break point conditions 
must be met before the actual break point 
occurs. If no count is specified, the 
default value is 1. Each time the 
Soft-ICE window is brought up, the 
counts are reset to the values originally 
specified. 

verb — Verb is a value that specifies what type 

access the break point will apply to. It 
can be set to 'R' for reads, 'W for write 
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C 3 
D 
D 
D 



'RW for reads and writes, or 'X' for 
execute . 

address — Address is a value that is made of two 16-bit 

words, separated by a colon. The first 
word is the segment address, and the 
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second word is the segment offset. The 
addresses can be constructed of registers 
expressions, and symbols. 

Thee address may also contain the special 
characters ••$", , and See section 

3-8 (Command Syntax) for a description 
of these special characters, 
■break-number — Break-number is an identification number 

that identifies the break point to use 
when you are manipulating break points 
(e.g., editing, deleting, enabling, or 
disabling them) . The break-number can 
be a hexadecimal digit from to F. 
list — List is a series of break-numbers separated 

by commas or spaces, 
mask — Mask is a bitmask that is represented as: 



LT 
D 



combination of l's, 
don't-care bits. 



O's, and X's. X's are 



Example: 



BPIO 21 W EQ M 1XXX XXXX 



D 
D 

This command will cause a break point to occur if port 
21H is written to with the high order bit set. 
GT, LT — GT and LT are command qualifiers that 

unsigned comparisons of values. 
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CHAPTER 4 



(I Using Break Point Commands 

4 . 1 Introduction 

4.2 Setting Break Points 

4 . 3 Manipulating Break Points 

51 

. 1 Introduction 

Soft-ICE has break point capability that has traditionally only been 
available with hardware debuggers. The power and flexibility of the 80386 
Jship allows advanced break point capability without additional hardware. 

-Break points can be set on memory location reads and writes, memory range 
reads and writes, program execution and port accesses. Soft-ICE assigns a 
one-digit hexadecimal number (0-F) to each break point. This break-number 
is used to identify break points when you set delete, disable, enable, or 
edit them. 

All of Soft-ICE 's break points are sticky. That means they don't disappear 
automatically after they've been used; you must intentionally clear or 
disable them using the BC or the BD commands. Soft-ICE can handle 16 break 
points at one time. You can have up to ten break points of a single type 
except for break points on memory location (BPMs) , of which you can only 
have four, due to restrictions of the 80386 processor. 

Break points can be specified with a count parameter. The count parameter 

□tells Soft-ICE how many times the break point should be ignored before the 
break point action occurs. 
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4.2 Setting Break Points 
[Commands: 



D 
D 
D 



BPM, BPMB, BPMW, BPMD — Set break point on memory 

access or execution 
BPR — Set break point on memory range 
BPIO — Set break point on I/O port access 
BP I NT — Set break point on interrupt 
BPX — Set/clear break point on execution 
CSIP — Set CS:IP range qualifier 
BPAND — Wait for multiple break points 

to occur 
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|J BPM, BPMB, BPMW, BPMD 

BPM, BPMB, BPMW, BPMD — Set break point on memory access or execution 
Syntax: 

BPM[ size] address [verb] [qualifier value] [C=count] 
size — B, W, D 

□B — Byte 
W — Word 
D — Double Word 

The size is actually a range covered by 



D 
D 
D 
D 
D 
D 

a 



this break point. For example, if 
double word is used, and the third 
byte of the double is modified, then a 
break point will occur. The size is 
also important if the optional qualifier 
is specified (see below) . 

verb — R, W, RW, or X 

qualifier — EQ, NE, GT, LT, M 

EQ — Equal 
NE — Not Equal 
GT — Greater than 
LT — Less Than 
M — Mask 

These qualifiers are only applicable to 
the read and write break points, 
value — A byte, word, or double word value, 

depending on the size specified. 

54 

omments : 



prhe BPM commands allow you to set a break point on memory reads or writes 
or execution. 



D 



If a verb is not specified, RW is the default. 
If a size is not specified, byte is the default. 



□Ml of the verb types except X cause the program to execute the 
instruction that caused the break point. The current CS:IP will be the 
instruction after the break point. If the verb type is X, the current 
CS:IP will be the instruction where the break point was set. 







If R is specified, then the break point will occur on read access and on 
write operations that do not change the value of the memory location. 



t 



If the verb type is R, W or RW, executing an instruction at the specified 
address will not cause the break point action to occur. 
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Note : 

If BPMW is used, the specified address must start on a word boundary. If 
BPMD is used, the specified address must point to a double word boundary. 



D 
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Example : 

BPM 1234: SI W EQ 10 C=3 
This command defines a break point on memory byte 
access. The third time that 10 hexadecimal is written to 
location 1234: SI, the break point action will occur. 
BPM CS:1235 X 
This command defines a break point on execution. 
The break point action will occur the first time that the 



G 
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instruction at address CS:1235 is reached. The current CS:IP will be the 
instruction where the break point was set. 



BPMW DS:FOO W EQ M OXXX XXXX XXXX XXXI 



D 



This command defines a word break point on memory write. The break point 
action will occur the first time that location DS:FOO has a value written 
Rto it that sets the high order bit to and the low order bit to 1. The 
other bits can be any value. 

BPM DS:1000 W GT 5 

This command defines a byte break point on memory write. The break point 
action will occur the first time that location DS:1000 has a value written 
to it that is greater than 5. 
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BPR 

BPR — Set break point on memory range 



D 
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Syntax : 

BPR start-address end-address [verb] [C=count] 
start-address , 

end-address — start-address and end-address specify 

memory range, 
verb — R, W, RW, T or TW 



Comments : 

The BPR command allows you to set a break point across a range of memory. 

All of the verb types except T or TW cause the program to execute the 

D instruction that caused the break point. The current CS:IP will be the 
'nstruction after the break point. 

There is no range break point on execution. If a range break point is 
[_desired on execution, R must be used. An instruction fetch is considered a 
read for range break points. 



If a verb is not specified, W is the default. 



The range break point will degrade system performance in certain 
circumstances. Any read or write within the 4K page that contains the 
break point range is analyzed by Soft-ICE. This performance degradation is 
usually not noticeable, however, degradation could be extreme in exception 
cases. 

The T and TW verbs enable back trace ranges on the specified range. They 

Gdo not cause break points, but instead log instruction information that 
can be displayed later with the SHOW cr TRACE commands. For more 
information on back trace ranges, see chapter 9. 
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Example : 

BPR B000:0 B000:1000 W 

This command defines a break point on memory range. 
The break point will occur if there are any writes to the 
monochrome adapter video memory region. 
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BPIO 
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BPIO — Set break point on I/O port access 



Syntax : 

BPIO port [verb] [qualifier value] [C=count] 
port — A byte or word value 
verb — R, W, or RW 

R — Read (IN) 
W — Write (OUT) 
qualifier — EQ, NE, GT, LT, M 

EQ — Equal 
NE — Not Equal 
GT — Greater Than 
LT — Less Than 
M — Mask 
value — A byte or word value 

Comments : 

[jPhe BPIO command allows you to set a break point on I/O port reads or 

l—writes. 
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f value is specified, it is compared with the actual data value read or 
'written by the IN or OUT instruction causing the break point. The value 
may be a byte or a word. If the I/O is to a byte port, then the lower 8 
bits are used in the comparison. 



The instruction pointer (CS:IP) will point to the instruction after the IN 
or OUT instruction that caused the break point. 



f a verb is not specified, RW is the default. 
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xample : 
BPIO 21 W NE FF 

This command defines a break point on I/O port 
access. The break point will occur if the interrupt 
controller one mask register is written with a value 
other than FFH. 

BPIO 3FE R EQ M 11XX XXXX 

This command defines a byte break point on I/O port 
read. The break point action will occur the first time 
that I/O port 3FE is read with a value that has the two 
high order bits set to 1. The other bits can be any value 
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BPINT 



j^BPINT — Set break point on interrupt 
Syntax: 

□BPINT int-number [ < AL | AH | AX >= value] [C = count] 
int-number — Interrupt number from - FF hex 
value — A byte or a word value 



D 



Comments : 



The BPINT command allows breaking on the execution of a hardware or a 
software interrupt. By optionally qualifying the AX register with a value, 
specific DOS or BIOS calls can be easily isolated. 

[jEf no value is specified, a break point will occur when the interrupt 
specified by int-number occurs. This interrupt can be a hardware, 
oftware, or internal interrupt. 



i 



The optional value is compared with the specified register (AH, AL, or AX) 
when the interrupt occurs. If the value matches the specified register, 
jthen the break point will occur. 

When the break point occurs, if the interrupt was a hardware interrupt, 
jthe instruction pointer (CSrIP) will point to the first instruction within 
the interrupt routine. The INT? command can be used to see where execution 
was when the interrupt occurred. If the interrupt was a software 
interrupt, when the break point occurs, the instruction pointer (CS:IP) 
will point to the INT instruction causing the interrupt. 
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Example : 

BPINT 21 AH=4C 



D 
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This command defines a break point on interrupt 21H 
The break point will occur when DOS function call 
4CH (terminate program) is called. 
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BPX 

PX — Set/clear break point on execution 
Syntax: 

BX [address] [C=count] 
Comments : 



The BPX command allows you to set or clear a point-and-shoot execution 
break point in source. When the cursor is in the code window the address 
is not required. The execution break point is set at the address of the 
current cursor location. If an execution break point has already been set 
at the address of the current cursor location, then the break point is 



cleared . 



If the code window is not visible or the cursor is not in the code window 
then the address must be specified. If an offset only is specified then 
the current CS register value used as the segment. 

Technical Note: 

BPX uses an interrupt 3 style of break point unless the specified address 
is ROM. This is used instead of a break point register to make more 
Pexecution break points available. If your circumstances require the use of 
a break point register for some reason (code not loaded yet for example) 
you can set an execution break point with the BPM command. 

D 
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Example : 

BPX. 1234 

This sets an execution break point at source line 1234. 
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CSIP 



CSIP — Set CS:IP range qualifier 
Syntax: 

CSIP [OFF [NOT] start-address end-address] 
NOT — When NOT is specified, the break point 

will only occur if the CS:IP pointer is 
outside the specified range. 
OFF — Turns off CS:IP checking 



D 



n. 



Comments : 

pThe CSIP command causes a break point to be dependent upon the location of 
1— the instruction pointer when the break point conditions are met. This 

function is often useful when a program is suspected of accidentally 
Qnodifying code outside of its boundaries. 

When break point conditions are met, the CS:IP registers are compared with 
r-a specified range. If they are within the range, the break point is 
activated. To activate the break point when CS:IP is outside the range, 
use the NOT parameter. 

Pvtfhen a CSIP range is specified, it applies to ALL break points that are 
Lburrently active. 

DIf no parameters are specified, the current CSIP range is displayed. 
Example: 



D 
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CSIP NOT F000:0 FFFF: 

This command causes the break points to occur only 
the CS:IP is NOT in the ROM BIOS when the break 
point conditions are met. 
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BP AND 

BPAND — Wait for multiple break points to occur 



D 



Syntax: 

BPAND list | * | OFF 
list — A series of break-numbers 

separated by commas or spaces 
* — ANDs together all break points 



^Comments : 

The BPAND command does a logical AND of two or more break points, 
activating the break point only when conditions for all break points are 

Linet. 



Sometimes conditions arise when you don't want a break point to occur 



until several different conditions are met. The BP AND command allows 
specifying two or more break points that must occur before the action is 
generated. This function allows more complex break point conditions to be 

Lset . 

Each time the BPAND command is used, the specified break point numbers are 
added to the list until BPAND OFF is used. 

You can tell which of the break-numbers are ANDed together by listing the 
break points with the BL command. The break points that are ANDed together 
will have an ampersand (&) after their break-number. 

Once break points have been ANDed together, each remains ANDed until it is 
Lkleared, or until BPAND is turned off. 



Example: 
[BPAND 0,2,3 

This command causes the conditions of the break points 0, 2, and 3 to be 
logically tied together. The break occurs only when the conditions of all 
three are met. For example, if the conditions of break points 2 and 3 have 
both been met at least once, but the conditions of break point have not 
r-been met at all yet, then the action will not occur until break point 
conditions are met. 
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0* . 3 Manipulating Break Points 



■Soft-ICE provides several commands for manipulating break points. 
Manipulation commands allow listing, modifying, deleting, enabling, and 
disabling of break points. Break points are identified by break-numbers 

C which are hexadecimal digits from to F. The break point manipulation 
commands are: 

BD — Disable break points 
BE — Enable break points 
BL — List break points 
BPE — Edit break point 
BPT — Use break point as a template 
BC — Clear break points 



D 
[ 
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BD 

BD — Disable break points 



Syntax: 

BD list | * 

list — A series of break-numbers separated 

by commas or spaces 
* — Disables all break points 



Comments : 



he BD command is used to temporarily deactivate break points. The break 



points can be reactivated with the BE (Enable break points) command. 



You can tell which of the break-numbers are disabled by listing the break 
points with the BL command. The break points that are disabled will have 
an asterisk (*) after their break-number. 

Example: 
BD 1,3 



D 
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This command temporarily disables break points 1 and 
3. 
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BE 

BE -- Enable break points 



Syntax: 

BE list | * 

list — A series of break-numbers separated 



D 



by commas or spaces 
* — Enables all break points 



Comments : 

The BE command is used to reactivate break points that were deactivated by 
the BD (Disable break points) command. 

Qjote that a break point is automatically enabled when it first defined. 

Example: 
BE 3 



D 
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This command enables break point 3 . 
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BL 

i — List break points 



Syntax: 
BL 

Comments : 

n 

The BL command displays all break points that are currently set. For each 
break point, BL lists the break-number, break point conditions, break 
j~point state, and count. 

The state of a break point is either enabled or disabled. If the break 
ppoint is disabled, an asterisk (*) is displayed after its break-number. If 
an enabled break point was used in a BPAND command, an ampersand (&) is 
displayed after its break-number. The break point that most recently 
caused an action to occur is highlighted. 

Dlhe BL command has no parameters. 



J 



Example: 
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BL 



This command displays all the break points that have 
been defined. A sample display, which shows four 
break points, follows: 

0) BPMB 1234:0000 W EQ 0010 C=03 

1) BPR B000:0000 B000:1000 W C=01 

2) BPIO 0021 W NE 00FF C=01 

3) BPINT 21 AH=4C C=01 

Note that in this example, break point 1 is preceded 
with an asterisk (*) , showing that it has been disabled 



70 

BPE 

BPE — Edit break point 



Syntax: 

BE break-number 

Comments : 

The BPE command loads the break point description into the edit line for 
modification. The command can then be edited using the editing keys, and 
re-entered by pressing the ENTER . This command offers a quick way to 
Qnodify the parameters of an existing break point. 

Example: 
BPE 1 



D 
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This command moves a description of break point 1 
into the edit line and removes break point 1. Pressing 
the ENTER key will cause the break point to be 
re-entered. 
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BPT 



QiJPT — Use break point as a template 



Syntax: 

BT break-number 

Comments: 

jThe BPT command uses an existing break point description as a template for 
a new break point. 

A description of the existing break point is loaded into the edit line. 
The break point referenced by break-number is not altered. This command 
offers a quick way to create a new break point that is similar to an 
existing break point. 

Example: 
BPT 3 



D 

This command moves a template of break point 3 into 

□the edit line. When the ENTER key is pressed, a 
new break point is added. 
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BC 

|^BC — Clear break points 

Syntax: 

□BC list | * 
list — A series of break-numbers separated 

by commas or spaces 
j-j * — Clears all break points 

Comments : 

Rrhe BC command is used to permanently delete one or more break points 
E 

D 

This command clears all break points. 
PAGE 74 IS EMPTY 

D 



Example: 
BC * 
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CHAPTER 5 

Using Other Commands 

5.1 Display and Edit Commands 

5.2 I/O Port commands 

5.3 Transfer Control Commands 

5 . 4 Debug Mode Commands 

5.5 Utility Commands 

5.6 Specialized Debugging Commands 

5.7 Windowing Commands 

5.8 Debugger Customization Commands 

5.9 Screen Control Commands 

5.10 Symbol and Source Line Commands 
5.1 Display and Edit Commands 
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Commands : 
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U — Unassemble instructions or display source 
Syntax : 

U [address] [L[=] length] 



U 




Unassemble instructions or display source 


R 




Display or change registers 


MAP 




Display system memory map 


D 




Display memory in the most recently 






specified format 


DB 




Display memory in byte format 


DW 




Display memory in word format 


DD 




Display memory in double word format 


E 




Edit memory in the most recently 






specified format 


EB 




Edit memory bytes 


EW 




Edit memory words 


ED 




Edit memory double words 


INT? 




Display last interrupt number 


? or H 




Display help information 


VER 




Display Soft-ICE version number 
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U 



D 



length — The number of instructions 

to be unassembled 



Comments : 

The U command displays the instructions of the program being debugged. 

If length is not specified, the length defaults to eight lines if 
i available, or one less than the screen length. 

If address is not specified, the command unassembles at address starting 

Gat the first byte after the last byte unassembled by a previous unassemble 
ommand. If the has been no previous unassemble command, the address 
defaults to the current CS:IP. 



D 



D 



f the code window is visible, the instructions are displayed in the code 
window. 



tEf source is loaded for the address range specified then source lines may 
be displayed depending on the current source mode. 

[j^ample: 

U $-10 

This command unassembles instructions beginning 
10 hexadecimal bytes before the current address. 



D 
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U .499 



EThis command displays the current source file starting at line 499. The 
code window must be visible and in source mode. 



D 
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.splay or change registers 



*R — Dii 
Syntax : 

j R register-name [ [ = ] value] ] 



register-name — Any of the following: 

AL, AH, AX, BL, BH, 
BX, CL, CH, CX, DL, 
DH, DX, DI, SI, BP, 
SP, IP, CS, DS, ES, SS, 
or FL 

value — If register-name is any name other than 

FL, value is a hex value or an 
expression. If register-name is FL, 
value is a series of one or more of the 
following flag symbols, each 
optionally preceded by a plus or 
minus sign: 

(Overflow flag) 
D (Direction flag) 

1 (Interrupt flag) 
S (Sign flag) 
Z (Zero flag) 
A (Auxiliary carry flag) 
P (Parity flag) 

C (Carry flag) 

[^Comments : 

The R command displays or changes register values. 

If no parameters are supplied, all register and flag value are displayed, 
as well as the instruction at the current CS:IP address. 

If register-name is supplied without a value, Soft-ICE displays the 
current value of the specified register and 
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prompts you for a new value. If register-name is FL, flags that are set 
are displayed as highlighted uppercase characters; flags that are cleared 
Lare displayed as non-highlighted lowercase characters. To retain the 
current value of a register, press ENTER. 

|lf both register-name and value are supplied, the specified register's 
contents are changed to the value. 

To change a flag value, use FL as the register-name, followed by the 
symbols of the flag whose values you want to toggle. To turn a flag on, 
precede the flag symbol with a plus sign. To turn a flag off, precede the 
■flag symbol with a minus sign. The flags can be listed in any order. 



1 
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Examples: 
RAH 5 



This command sets the AH register equal to 5. 
R FL = OZP 

This command toggles the 0, Z, and P flag values. 
R FL 

This command displays the current flag values, and 
allows them to be changed. 

RFL + A-C 

This command toggles the flag value, turns on the 
flag value, and turns off the C flag value. 



o 

f 



80 

MAP 

MAP — Display system memory map 



JjByntax : 
MAP 

P 

Comments: 

L The MAP command displays the names, locations, and sizes of system memory 
components. The size is displayed in paragraphs. One paragraph is 
equivalent to 10 hexadecimal bytes. 

The component that the CS:IP register currently points to is highlighted. 
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Use the MAP command when: 

* A break point occurs and CS:IP is not in a known 
memory region. 

* You want to get control within a resident program 
or system program. A range break point can be set 
based on the starting address and size reflected by 
MAP. 

* You suspect a program or system component of 
writing over code outside of its memory space. 
MAP is used to obta 



Q 
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m the memory address of the 

region to use with the CSIP command. 
* You need to find out which resident program owns 
certain interrupt vectors. 



Example: 




D 
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MAP 

The following is a sample display produced by the 
command : 

Start Length 

0000:0000 0040 Interrupt Vector Table 
0040:0000 0030 ROM BIOS Variables 
0070:0000 00FE I/O System 
016E:0000 06B7 DOS 

0842:0000 02CE DOS File Table & Buffers 
A000:0000 5E00 System BUS 
F000:0000 1000 ROM BIOS 

Versions of DOS lower than 3.1 display program 
addresses instead of displaying the program names. 
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D, DB, DW, DD 
D, DB, DW, DD — Display memory 
Syntax: 



D 

D 



D [size] [address] [L[ = ] length] 
size — B — Byte 

W — Word 

D — Double Word 

length — The number of bytes to be 
displayed. 



Comments : 

The D command displays the memory contents of the specified address. 



The contents are displayed in the format of the size specified. If no size 
is specified, the last size used will be displayed. The ASCII 
representation is also displayed for all forms. 

If address is not specified, the command displays memory at the address 
'starting at the first byte after the last byte displayed. 

If length is not specified, it defaults to eight lines, or fewer if the 
window is smaller. 

If the data window is visible, the data is displayed in the data window 
and the length is ignored. 

n 

Example: 

DW DS:00 L=8 

This command displays, in word format and in ASCII 
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format, the value of the first eight bytes of the current 
data segment. 
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E, EB, EW, ED 
, EB, EW, ED — Edit memory 



jjSyntax : 



D 
D 



E [size ] address [data-list] 

size — B — Byte 
W — Word 
D — Double Word 



D 



data-list — list of data objects of the specified size 

(Bytes, Words or Double Words) or 
quoted strings separated by commas 
or spaces. The quoted string can 
begin with a single quote or a double 
quote . 

[^Comments: 

The E commands display the memory contents at the specified address, and 
[-allow you to edit the values. 



These commands display the memory contents in ASCII format, and in the 
format of the size specified. 



memory editor is provided for quick memory updates. Memory can be edited 
by typing ASCII characters, or by typing byte, word, or double word 

□values . If no size is specified, the last size used will be assumed. The 
memory Editing key strokes are: 
@ — Move cursor up 
@ — Move cursor down 
@ — Move cursor right 
@ — Move cursor left 
SPACE — Move cursor to next element 



D 
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TAB — Toggle between numeric and 
ASCII areas 

ESC or 

ENTER — Exit memory editor 



As values are input, the actual memory locations are updated. All numeric 
lvalues are hex numbers. To toggle between the ASCII and numeric display 
areas, press the TAB key. 

If the data window is visible, the data is edited in the data window, 
^otherwise the data is edited in the command window. 

The data display length defaults to 8 lines if in the command window, or 
!to the size of the data window if it's visible. 



If no parameters are supplied, the cursor moves into the data window if 
the data window if visible. If the data window is not visible, the data is 



n 



edited in the command window at the last address displayed or edited 



D Examples : 
EB 1000:0 

This command displays, in byte format, up to six lines 
containing both the numeric and the ASCII 
representation of the values of the data starting at 
location 1000:0000. Once the lines are displayed, you 
can edit the values. 
EB 8000:0 "Hello", 0D 

This command replaces the values starting at locatio 
8000:0000 with the string "Hello" followed by a carriage 
return . 
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TNT? — Display last interrupt number 
Syntax: 
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INT? 



D 



INT? 



Comments : 

CThe INT? command displays the address and the number the last interrupt 
that happened. 

Example: 

□ INT? 
An example of the display produced by the INT? 
command follows: 

Last Interrupt: 16 
At: 0070:0255 



D 



D 

□ 
D 



This example shows that the last interrupt generated in 
the system before the Soft-ICE window was brought up 
was an interrupt 16 hexadecimal, at location 
0070:0255H. If the last interrupt that happened was a 
software interrupt, unassembling the code at 
0070:0255H will show the interrupt instruction. If it 
was a hardware interrupt, unassembling the code will 
show the instruction that was executing when the 
hardware interrupt occurred. 

86 

? or H 



Display help information 

H > [command | expression] 
Comments : 

[~jrhe ? command and the H command both display help information. 

If no parameters are specified, help displays short descriptions of all 
j-jthe commands and operators, one screen at a time. Press any key to 



or H — 
Syntax: 
< ? I 



continue, or press ESC to quit displaying help. 

Hlf command is specified, help displays more detailed information on the 
Lspecified command, including the command syntax and an example. 

If expression is specified, the expression is evaluated and the result 
[Jiisplayed in hexadecimal, decimal, and ASCII. 

(-Examples: 
? ALTKEY 

This command disp 
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lays information about the 

ALTKEY command, including its syntax and an 
example, 
H 10 + 14*2 

This command displays: 0038 00056 "8". These are the 
hexadecimal, decimal and ASCII representations of 
value of the expression "10 + 14*2". 
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VER 



"ITER — Display Soft-ICE version number 

U 

Syntax: 



D 



VER 



Example: 
VER 

This command displays the Soft-ICE version 

and the Nu-Mega Technologies copyright message. 
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5.2 I/O Port Commands 



D 



Commands : 

I or IB — Input from byte I/O port 
IW — Input from word I/O port 
O or OB — Output to byte I/O port 
OW — Output to word I/O port 



D 

D 

I, IB, IW — Input from I/O port 

[^Syntax : 
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I, IB, IW 



a 

D 



I [size] port 

Size — B — Byte 
W — Word 

port — A byte or word value 



Comments : 

The input from port commands are used to read and display a value from a 
hardware port. Input can be done From byte or word ports. If no size is 
specified, the default is byte. 

Example : 
I 21 

□This command displays the mask register for interrupt 
controller one. 
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O, OB, OW 
0, OB, OW, — Output to I/O port 



QSyntax: 



D 
D 



[size] port value 
size — B — Byte 
W — Word 

port — A byte or word value 
value — A byte for a byte port or a word 

for a word port 



Comments : 

The output to port commands are used to write a value to a hardware port. 
Output can be done to byte or word ports If no size is specified, the 
default is byte. 

Example : 
21 FF 

This command masks off all the interrupts for interrupt 
controller one. 
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5.3 Transfer Control Commands 



Commands : 

X — Exit from Soft-ICE window 

G — Go to address 

T — Trace one instruction 

P — Program step 

HERE — Go to current cursor line 

GENINT — Force an interrupt 

EXIT — Force exit of current DOS program 

BOOT — System boot (retain Soft-ICE) 

HBOOT — Hard system boot (total reset) 
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x 

X — Exit from Soft-ICE window 
Syntax: 
X 



D 



Comments : 

The X command exits the Soft-ICE window and restores control to the 
program that was interrupted to bring up Soft-ICE. The Soft-ICE window 
disappears. If any break points have been set, they become active. 

Example: 
X 
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jj3 — Go to address 
Syntax: 

G [=start-address] [break-address] 
Comments : 

[(The G command exits from the Soft-ICE window with a single one-time 
execution break point set. In addition, all sticky break points are armed. 

pExecution begins at the current CS:IP unless the start-address parameter 
|_Jis supplied. In that case execution begins at start-add 

D 
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ress. Execution 

continues until break-address is encountered, the window pop-up key 
sequence is used, or a sticky break point occurs. 



The break-address must be the first byte of an instruction opcode. 



ft 



hen the specified break-address is reached, the current CS:IP will be the 
instruction where the break point was set. 

jjrhe G command with no parameters behaves the same as the X command. 

The non-sticky execution break point uses an 80386 break point register, 
unless all break point registers have been allocated to sticky break 
points. In that case, an INT 3 style break point is implemented. When this 
case occurs, the G and P commands will not work correctly in ROM. An error 
message will be displayed if this is attempted. 



5 

E 

D 
D 



xample : 

G CS:1234 

This command sets a one time break point at CS:1234 



□ 
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T 

T T — Trace one instruction 
yntax: 

T [=start-address] [count] 



Comments : 

CjThe T command single steps one instruction by utilizing the single step 
jciag. 

Execution begins at the current CS:IP unless the start-address parameter 
' 'is specified. If start-address is specified, CS:IP is changed to start- 
address prior to single stepping. 

If count is specified then Soft-ICE single steps count time The TRACE 
Jcommand will continue until the count is exhausted or the Esc key is 
pressed, regardless of which break points are reached. 

In source mode, the T command steps to the next source statement. If the 
current statement is a procedure or function call, and source exists for 
the routine being called, T steps into the call. If there is no source 
[available for the called procedure or function, T steps over the routine 



Example : 

T = 1284 3 

This command single steps through three instruction 
starting at memory location 1284. 
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— Program step 



ax : 



D 
D 



li 



Comments : 

The P command is a logical program step. One instruction at the current 
CS:IP is executed unless the instruction is a call, interrupt, loop, or 

epeated string instruction. In those cases, the entire routine or 
iteration is completed before control is returned to Soft-ICE. 

The P command uses a one-time execution break point. The non-sticky 
Execution break point uses an 8038 6 break point register, unless all break 
point registers have been allocated to sticky break points. In that case, 
an INT3 style break point is implemented. When this case occurs, the P and 

commands will not work correctly in ROM. An error message will be 
displayed if this is attempted. 

[jln source mode, the P command steps to the next source statement. If the 
current statement is a procedure or function call, the P command steps 



over the it 
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Example: 
P 

This command executes one 'program step'. 
96 

HERE 

HERE — Go to current cursor line 
yntax: 
HERE 



D 

Comments : 

.The HERE command executes until the program reaches the current cursor 
•line. HERE is only available when the cursor is in the code window. If the 
Msode window is not visible or the cursor is not in the code window, use 
the G command instead. 

~| 

(The HERE command exits from Soft-ICE with a single one-time execution 
break point set. In addition, all sticky break points are armed. 

Execution begins at the current CS:IP and continues until address of the 
current cursor position in the code window encountered, the window pop-up 
key sequence is used, a sticky break point occurs. 



D 



The non-sticky execution break point uses an 8 0386 break point register, 
unless all break point registers have been allocated to sticky break 
points. In that case, an INT 3 style break point is implemented. When this 
case occurs, the HERE command will not work correctly in ROM. An error 
message will be displayed if this is attempted. 



D 



Example: 
1 HERE 

This example sets an execution break point at the 
current cursor position, then exits from Soft-ICE and 
begins execution at the current CS:IP. 
Default Function Key: F7 
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GENINT 

GEN1NT — Force an interrupt 

jsyntax : 

GENINT INT1 | INT3 | NMI | interrupt-number 



interrupt-number — a number in the range 00 - FF 



Tpomments: 

UThe GENINT command forces an interrupt to occur. This function can be used 
to hand off control to another debugger when using Soft-ICE with another 

D software debugger. It can also be used to test interrupt routines. 
The GENINT command simulat 
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es the processing sequence of a hardware 

interrupt or an INT instruction. It pushes the flags, the CS register, and 
the IP register, then changes the value of the CS and IP registers to the 
value of the interrupt vector table entry corresponding with the specified 
interrupt number. 

Example: 

GENINT NMI 

□This forces a non-maskable interrupt. This will give 
control back to CodeView if Soft-ICE is being used as 
an assistant to CodeView. 
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EXIT 



Q2XIT — Force exit of current DOS program 
Syntax: 

n 

EXIT [R] [D] 
R — Restore the interrupt vector table 
j~j D — Delete all break points 

Comments: 

j-The EXIT command attempts to abort the current program by forcing a DOS 
exit function (INT 21H, function 4CH) This command will only work if the 

HDOS is in a state where it is able to accept the exit function call. If 
this call is made from certain interrupt routines, or other times when the 

j~jX)S is not ready, the system may behave unpredictably. 

This function does NOT do any system resetting other than the interrupt 
rtable when the R option is used. This means that BIOS variables, video 
modes and other systems level data are not restored. 

Using the R option will cause the interrupt vectors to be restored to 
[whatever they were the last time they were saved. Soft-ICE saves the 
interrupt vectors when it is loaded, when a program is loaded with 
LDR.EXE, and when the VECS S command is used. 

jNote : 

To re-start a program that has been loaded with the Soft-ICE program 
loader (LDR.EXE) do the following: 
EXIT R 
LDR prog. EXE 







DThe EXIT command will restore the interrupt table to the values it 
contained before the program was loaded, then 
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exit to the command processor. By running the LDR utility and specifying 

Cthe .EXE suffix, the program is loaded back in without re-loading symbols 
and source. The symbols and source will remain in memory. 

Caution: 

he EXIT command should be used with care. Since Soft-ICE can be popped up 
at any time, a situation can occur where the DOS is not in a state to 
accept an exit function call. Also, the EXIT command does not do any 

D program specific resetting. For instance, the EXIT command does not reset 
I 



D 



the video mode. If your program has placed the video BIOS and hardware in 
a particular video mode, it will stay in that mode after the EXIT command. 



Example: 
EXIT R 

□Restores the interrupt table and exits the current 
program. The R option should be used if exiting from 
a program loaded with the Soft-ICE program loader 
LDR.EXE. 

100 



D 



BOOT 

BOOT — System boot (retain Soft-ICE) 

|syntax : 
BOOT 



P 

Comments : 

The BOOT command resets the system and retains Soft-ICE. BOOT is required 
nto debug boot sequences, DOS loadable drivers, and non-DOS operating 
systems. 

CBOOT is implemented with an Interrupt 19H ROM BIOS call. In some instances 
memory may be corrupted to the point where Interrupt 19 will not work. If 
this occurs, bring up Soft-ICE and use the HBOOT command. 

C'(For BOOT to work properly, Soft-ICE should be installed as a loadable 
Idriver in CONFIG.SYS before any other device drivers. This is so Soft-ICE 
can restore the original system state as accurately as possible. 

Example : 
BOOT 

This command makes the system reboot. Soft-ICE 
remains resident. 



1 
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HBOOT 

•HBOOT — Hard system boot (total reset) 
Syntax: 
HBOOT 



Comments : 

The HBOOT command resets the entire system. Soft-ICE is not retained in 
the reset process. HBOOT is sufficient unless an adapter card requires a 
power-on reset. In those rare cases, the machine power must be recycled. 

Example : 
HBOOT 

This command makes the system reboot. Soft-ICE 
must be reloaded. 



a 
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5 . 4 Debug Mode Commands 



Set action after break point is reached 
Set DOS /ROM BIOS re-entrancy 

warning mode 
Break out any time 
Direct Interrupt 3's to Soft-ICE 

D 103 

ACTION 

Q^CTION — Set action after break point is reached 
Syntax: 

ACTION [INT1 | INT3 | NMI | HERE | int-number] 

Any valid interrupt number (O-FFH) . 

Use this option only if a user-supplied 
break point qualification routine has 
taken over that interrupt vector (see 
section 11.2) . 

Comments : 

The ACTION command determines where control is given when break point 
conditions have been met. In most cases, the desired action is INT3 or 
HERE, INT3 is typically used if Soft-ICE is being used with a host 
debugger, HERE is used when it is desired to return to Soft-ICE when break 
Lpoint conditions have been met, INT1 and NMI are alternatives for certain 
debuggers that will not work with the INT3 option. For instance, CODEVIEW 
works best with ACTION set to NMI. 



Commands: 
ACTION 
WARN 



D 



BREAK 
I3HERE 



int-number — 

D 



Use int-number if there is a user-supplied break point qualification 
routine installed. Using int-number without having a user-supplied break 
point qualification routine installed causes an error. For more 
information, see section 11 . 2 , 'User-Qualified Break Points'. 

If no parameter is supplied with the ACTION command, the current action is 
displayed. 

The default action is HERE. 
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Example: 
~] ACTION HERE 

This command specifies that control will return to Soft-ICE when break 
point conditions have been met. 

105 

WARN 

n 

WARN — Set DOS /ROM BIOS re-entrancy warning mode 

j-jSyntax: 



D 

WARN [ON | OFF] 

Lcomments: 
The WARN command is provided for usi 

D 
D 
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g Soft-ICE with debuggers that use 
DOS and ROM BIOS., Many debuggers use DOS and ROM BIOS for screen output 

Gand for receiving keystrokes. Since DOS and ROM BIOS are not fully re- 
entrant, these debuggers may not work properly if break point occurs while 
the DOS or ROM BIOS is executing. 

[jlf WARN ON is set, and ACTION is not HERE, then control will come to Soft- 
ICE before the actual action occurs. The system displays the current CS:IP 
and gives you the choice of continuing or returning to Soft-ICE. 
Generally, you should choose to return to Soft-ICE to continue your 
debugging. Only continue with the host debugger if you know your debugger 
will not cause DOS or ROM BIOS to be re-entered. 



Q 



WARN mode should be turned on to use Soft-ICE with DEBUG, SYMDEB, and 
CODEVIEW. 

jjlf no parameter is specified, the current state of WARN is displayed. 
The default is WARN mode OFF. 
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Example: 
WARN ON 

This command turns on DOS /ROM BIOS re-entrancy 
warning mode. 
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BREAK 

BREAK — Break out any time 
^Syntax : 

BREAK [ON I OFF] 



Comments : 

The BREAK command allows popping up the Soft-ICE window when the system is 
["hung with interrupts disabled. Break mode can be used for the entire 
debugging session, or it can be turned on and off when it is required. 

Break mode degrades system performance slightly. This performance 
degradation must be weighed against the necessity of breaking out of a 
hung program. A user may want to have break mode on all the time, even 
though performance is degraded, because the program could hang at any 

j~time. 

Unlike other debuggers that can also be brought up at any time, Soft-ICE 
rdoes not require an external switch. When BREAK is on, the Soft-ICE window 
oan be brought up at any time by pressing the current key sequence. 

If no parameter is specified, the current state of BREAK is displayed. 







The default is BREAK mode OFF. 

Example: 
' BREAK ON 

This command turns on break mode. This means that 
the Soft-ICE window can be brought up at any time, 



even if interrupts are disabled. 
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13 HERE 



[jl3HERE — Direct Interrupt 3's to Soft-ICE 
,_Syntax : 

13 HERE [ON | OFF] 
[""Comments : 

□The 13 HERE command lets you specify that any Interrupt 3 will bring up the 
Soft-ICE window. This feature is useful for stopping your program in a 
specific location. 



To use this feature, place an INT 3 into your code at the location where 
you want to stop. When the INT 3 occurs, it will bring up the Soft-ICE 
[window. At this point, you can use the R IP command to change your 
Jinstruction pointer to the instruction after the INT 3 , then you can 
continue debugging. 

P 

jlf no parameter is specified, the current state of 13 HERE is displayed. 
r-The default is 13HERE mode OFF. 



D 



xample : 
13 HERE ON 

This command turns on 13HERE mode. Any INT 3's 
generated after this point will bring up the Soft-ICE 
window. 
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5.5 Utility Commands 



□ 



Commands : 

A — Assemble code 

S — Search for data 

F — Fill memory with data 

M — Move data 

C — Compare two data blocks 
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A — Assemble code 
Syntax: 

A [address] 
Comments : 

The Soft-ICE assembler allows you to assemble instructions directly into 
memory. The assembler supports the basic 8086 instruction set with the 
80186 and 80286 real address mode extensions. Numeric co-processor 
instructions and 80386 specific instructions, registers and addressing 
modes can NOT be assembled. 



1 



D 

The A command enters the Soft-ICE interactive assembler. An address is 

G displayed as a prompt for each assembly line After an assembly language 
instruction is typed in and ENTER is pressed, the instructions are 
assembled into memory at the specified address. Instructions must be 
rpntered with standard Intel format. Press ENTER at an address prompt to 
lexit assembler mode. 

Clf the address range in which you are assembling instructions is visible 
jin the code window, the instructions will change interactively as you 
assemble. 



Dhe Soft-ICE assembler supports the standard 8086 family mnemonics, 
however there are some special additions : 

* The DB mnemonic is used to define bytes of data 

□directly into memory. The DB command is 
followed by a list of bytes and/or quoted strings 
separated by spaces or commas. 

* The RETF mnemonic represents a far return. 

□* WORD PTR and BYTE PTR are used to 
determine data size if there is no register 
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argument, for example: MOV BYTE PTR 
ES:[ 1234], 1. 

■ Use FAR and NEAR to explicitly assemble far and 

near jumps and calls. If FAR or NEAR is not 
specified then all jumps and calls are near. 

■ Operands referring to memory locations should 

placed in square brackets, for example: MOV 
AX, [1234] . 



Example: 

A CS:1234 
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This command prompts you for assembly instruction 
then assembles them beginning at offset 12 34H with 
the current code segment. Press ENTER at the 
address prompt after entering the last instruction 
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S — Search for data 



Syntax : 



□S address L length data-list 
data-list — list of bytes or quoted strings separated 

by commas or spaces. .A quoted string 
can begin with a single quote or a 
double quote. 

length — length in bytes 

n 

Comments : 

The S command searches memory for a series of bytes or characters that 
matches the data-list. The search begins at the specified address and 

J 



ontinues for the length specified. The address of each occurrence found 
in the range is displayed. 

^Example : 

S DS:SI+10 L CX 'Hello' , 12 , 34 
This command searches for the string 'Hello' followed 
by the bytes 12H and 34H starting at offset SI+10 in 
the current data segment and ending CX bytes later. 



□ 
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' — Fill memory with data 
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Syntax : 



F address L length data-list 

data-list — list of bytes or quoted strings separated 

by commas or spaces. A quoted string 
can begin with a single quote or a 
double quote, 

length — length in bytes 



Comments : 

The F command fills memory with the series of bytes or characters 
specified in the data-list. Memory is filled starting at the specified 
address and continuing for the specified length, repeating the data-list 
lif necessary. 



□ 
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Example: 

F 8000:0 L 100 'Test' 

This command fills memory starting at 8 000:0 for a 
length of 100H bytes with the string 'Test'. The string 
Test' is repeated until the fill length is exhausted. 



/ 1 
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M — Move data 



n 



Syntax: 



D 



M start-address L length end-address 
length — length in bytes 



Comments : 

The M command moves the specified number of bytes from the start-address 
in memory to the end-address in memory. 



Example: 

M 1000:0 L 200 2000:0 

This command moves 2 00H bytes from memory 
location 1000:0 to memory location 2000:0. 



D 
D 



114 



D 



C — Compare two data blocks 
Syntax: 



D 



C addressl L length address2 
length — length in bytes 



Comments : 

The C command compares the memory block specified by addressl and the 
length with the memory block specified address2 and the length. 
When a byte from the first data block does not match a byte from the 
jsecond data block, both bytes are displayed, along with their addresses 

Example: 

C 5000:100 L 10 6000:100 
This command compares the 10H bytes starting at 
memory location 5000:100 with the 10H bytes starting 
at memory location 6000:100. 
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5.6 Specialized Debugging Commands 



D 
D 
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Commands 
, SHOW 
TRACE 
XT 
XP 
XG 

XRSET 
VECS 
SNAP 
EMMMAP 
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Display instructions from history buffer 

Enter trace simulation mode 

Single step in trace simulation mode 

Program step in trace simulation mode 

Go to address in trace simulation mode 

Reset back trace buffer 

Save/ restore/ compare interrupt vectors 

Take snap shot of memory block 

Display EMM allocation map 



SHOW 



SHOW — Display instructions from history buffer 



Syntax: 



□ 
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SHOW [B start] 
B — This tells the show command to start 

the display with the oldest instruction 
in the back trace buffer. 

start — The number of instructions back from 

the buffer end (last instruction 
captured) to begin display. 



Comments : 

The SHOW command displays instructions from the back trace history buffer 
If source is available for the instructions then the display is in mixed 
mode, otherwise only code is displayed. 



SHOW allows scrolling through the back trace buffer with the up, down, 
Pageup and PaqeDn keys. To exit from SHOW you must press the Esc key. 



D 



Preceding the address of each instruction is the buffer entry number. This 
number shows how deep into the buffer you are displaying. The higher the 
Qmmber, the deeper you are into the buffer. 

Note: 

Before using the SHOW command, instructions must have been logged with a 
ack trace range. See chapter 9 for more information on back trace ranges. 
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Hints: 

It is often useful to have the code window visible with the actual code of 

Dthe region you are displaying from the back trace buffer. When you compare 
the actual instruction flow to code, displayed jumps and calls are usually 
less confusing. 
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Using SHOW in conjunction with the TRACE command will allow you to see the 
instructions in the back trace history buffer from two different points of 
view. 
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Example : 
SHOW 40 

This example will displays starting with the 40th 
instruction back in the back trace buffer. 
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TRACE 

TRACE — Enter trace simulation mode 
Syntax: 



D 
D 



TRACE [start] | [OFF] 

start — The number of instructions back from 

the buffer end (last instruction 
captured) to begin trace simulation 

OFF — Exit trace simulation mode. 



Comments : 

The TRACE command allows you to replay instructions from the instruction 
back trace history buffer just as if they were being executed for the 
first time. To use trace simulation mode you must have the code window 
Ll visible After entering trace simulation mode you use the XT, XP and XG 
commands to trace through the instructions in the buffer. 



Q?o exit trace simulation mode type TRACE OFF. 

TRACE with no parameters specified displays whether trace simulation mode 
is on or off. 

Note: 

Before using the TRACE command, instructions must have been logged with a 
back trace range. See chapter 9 for more information on back trace ranges. 



Hints: 

race simulation mode is most useful when the code window is visible. It 
is often useful to use TRACE in conjunction with the SHOW command. This 
Hows the 
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instructions in the back trace history buffer to be viewed simultaneously 
in two different forms. 



Example: 

TRACE 40 

This example enters trace simulation mode starting 40 
instructions back from the last instruction logged. It 
will remain in trace simulation mode until TRACE 
OFF is entered. 
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XT 

u 

■-XT — Single step in trace simulation mode 

j~jsyntax : 

XT [R] 

j~j R — Single step in reverse direction. 
Comments : 

CThe XT command single steps through the instruction back trace history 
buffer. This command acts like the T command for normal debugging. Note 
that the registers do NOT change while stepping in trace simulation mode 
except CS and IP, 

Qrhe XT inst 
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ruction allows you to replay instructions from the back trace 
history buffer, 



Note: 

Before using XT you must be in trace simulation mode. See chapter 9 and 

nthe TRACE command in this section for more information on back trace 
ranges . 



pint: 

jlf you are using XT frequently, like any other Soft-ICE command it can be 
assigned to a function key. 



□Example: 
XT 

This command single steps one instruction in trace 
simulation mode. 
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XP 

XP — Program step in trace simulation mode 
Syntax : 
XP 



Comments : 

The XP command does a logical program step through the instruction back 

D^race history buffer. This command acts like the P command for normal 
debugging. Note that the registers do NOT change while stepping in trace 
simulation mode except CS and IP. 



he XP instruction allows you to replay instructions from the back trace 
history buffer. 

Note: 

Before using XP you must be in trace simulation mode. See chapter 9 and 
the TRACE command in this section for more information on back trace 
ranges . 

Hint: 

If you are using XP frequently, like any other Soft-ICE command it can be 
assigned to a function key. 
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Example : 
XP 

This command executes one program step in trace 
simulation mode. 
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XG 

XG — Go to an address in trace simulation mode 



j~jsyntax: 

X [R] address 

R — Search for address in reverse direction. 



□ 
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address — Address to go to in the back trace 

history buffer. 



1 



Comments : 

[The XG command moves the instruction pointer to the next occurrence of the 
specified address in the back trace history buffer. If R is specified 
preceding the address, then the instruction pointer is moved to the 
previous occurrence the specified address in the back trace buffer. 



he address must be the first byte of an instruction opcode, 
"jrhe XG is analogous to the G command in normal debugging. 
Note: 

Cpefore using XG you must be in trace simulation mode. See chapter 9 and 
the TRACE command in this section for more information on back trace 
ranges. 



D Example: 
XG 273:1030 

This command moves the instruction pointer to the 
next instance of the instruction at address 273:1030. 



D 



D 




Q 
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XRSET 

XRSET — Reset back trace history buffer 
Syntax: 
XRSET 
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VECS 



Comments : 

The XRSET command resets the back trace history buffer. This command 
should be executed before setting a back trace range if there is unwanted 
instruction information in the back trace buffer. 

□Example: 
XRSET 

This command resets the back trace buffer. 

a 

D 

VECS — Save/restore/ compare interrupt vectors 

[^Syntax : 

VECS [C|S|R] 

C — Compare current table with stored table 
S — Save current interrupt table to buffer 
R — Restore interrupt table from buffer 

p 

Comments : 

The VECS command allows you to save and restore the interrupt table to an 
internal Soft-ICE buffer. The actual table can also be compared to the 



stored table with the differences displayed. 



When the C option is used to compare the current interrupt vector table 
with the stored copy the output is in the following format: 



D 



address old-vector new-vector 
Each vector that has changed is displayed. 



he interrupt vector table is initially stored when Soft-ICE is loaded. It 
is also automatically stored when a program loaded with LDR.EXE. Only one 
copy of the interrupt vector table is stored, so each time VECS S is 
executed, previous copy of the interrupt table is overwritten. 



HEf no parameters are specified, the entire interrupt vector table is 



Displayed. 



j 
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Example: 
VECS c 

This command compares the actual interrupt vector 
table with one that had been previously stored in the 
Soft-ICE internal VECS buffer. 



D 
1 
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SNAP 

NAP — Take snap shot of memory block 



pSyntax: 



D 



'SNAP [C | S | R] addressl address2 

C — Compare buffer with address range 
S — Save address range to buffer 
R — Restore buffer to address range 



Comments : 

._The SNAP command takes a snap shot of a memory block for later comparison. 
The S option copies a block of memory to a buffer in extended memory. The 

r-C option displays differences between the buffer in extended memory and 
the actual memory specified by the address range. The R option copies the 
buffer in extended memory to the address range in conventional memory. 

[~When the C option is used to compare the buffer with the address range the 
output is in the following format: 

|~j address old-data new-data 

Each byte that has changed is displayed. 

The address is usually not necessary for the C and R options. If the 
-address is not specified, the address from the last time SNAP was entered 
with a specified address used. 

D 

Notes: 

o use the SNAP command you must have specified the /TRA XXXX switch on 




the S-ICE.EXE line in CONFIG.SYS. 
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The SNAP command saves data in the back trace history buffer. If you are 

Gsing back trace then you will have a conflict with SNAP. Specifically, 
SNAP will overwrite back trace information if you do a SNAP S when 
instruction history is in the back trace buffer. Conversely, if you have 
saved a region with SNAP, then enabling a back trace range will overwrite 
the SNAP buffer. 

Example: 

□SNAP S 2000:0 4000:0 
This command stores the data block from 2000:0 to 
4000:0 in the Soft-ICE back trace buffer. 
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EMMMAP 

EMMMAP — Display EMM allocation map 



QSyntax : 

EMMMAP 
["Wonts: 

^he EMMMAP command displays each physical page that is available for EMM 



memory and the pages that are currently mapped in. 



P 



lote: 

The Soft-ICE EMM feature must be enabled to use this function. See chapter 
r-B for more information on enabling EMM capability. 



4 
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xample: 
EMMMAP 

This example displays the current EMM allocation in 

in the following form. 

Phy page Seg address Handle/Page 

00 D000 FFFF 

01 D400 0001/0000 

02 D800 0001/0001 

03 DC00 0001/0002 

In this example, physical page is located at D000 and 
is unmapped. Physical page 1 is located at D400 and 
has handle l, page mapped into it. Physical page 2 is 
located at D800 and has handle 1, page I mapped into 
it. Physical page 3 is located at DC00 and has handle 
page 2 mapped into it. 

129 
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^5.7 Windowing Commands 



D 



Commands : 

WR — Toggle register window 

WC — Toggle/set size of code window 

WD — Toggle/set size of data window 

EC — Enter/ exit code window 



— Locate current instruction 



D 
D 
D 



Three window types may be created with Soft-ICE: 
register, data, and code. Any of these windows can be 
toggled on or off at any time. The data and code 
windows can be of variable size; the register window is 
fixed in size. The windows always remain in a fixed 
order. Starting from the top of the screen, the order is 
register window, data window, then code window. 



D 
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WR 

WR — Toggle register window 
Syntax : 
WR 



1 



Comments : 

The command makes the register window visible if not currently visible. If 
the register window is currently visible, WR removes the register window. 



The register window displays the 8086 register set and the processor 
lags. 



D 



Default Function: F2 
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. WC 



QtfC — Toggle/set size of code window 
Syntax : 



D 
D 

D 
D 
D 
D 




WC [window-size] 

window-size — a decimal number between one and 21. 

^Comments : 
If win 



D 



dow-size is not specified, this command toggles the code window. If 
it was not visible it is made visible, and if it was visible it is 

C removed . 
I 

If window-size is specified the code window is resized, or it was not 

D visible it is made visible with the specified size. 
[ 

Note : 

GIf you wish to move the cursor to the code window use the EC command. See 
description of the EC command for more details. 



D 



D 
D 



Example : 
WC 12 

If no code window is present, then a code window 12 
lines in length is created. If the code window is 
currently on the screen, it is resized to 12 lines. 
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WD 

WD — Toggle/set size of data window 



Syntax: 



D 



WD [window-size] 

window-size — a decimal number between one and 21. 



Comments : 

DQCf window-size is not specified, this command toggles the data window. If 
tit was not visible it is made visible, and if it was visible it is 
removed . 

If window-size is specified the data window is resized, or it was not 
visible it is made visible with the specified size. 



D 
D 
D 
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Example: 
WD 1 

If no data window is present then a data window of one 
line is created. If the data window is currently on the 
screen, it is resized to one line. 
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EC 

EC — Enter/ exit code window 
Syntax: 
EC 

Comments : 

•The EC command toggles the cursor location between the code window and the 
-command window. If the cursor was in the command window it is moved to the 

code window, and if the cursor was in the code window it is moved to the 
jjcommand window. 

When the cursor is in the code window several options become available 
pthat make debugging much easier. The options are: 



D 
D 
D 
D 
D 
D 
D 
D 
D 
D 
C 



' Point-and-shoot break points 

Point-and-shoot break points are set with the BP 
command. If no parameters are specified with the 
BPX command an execution break point is set at 
the location of the cursor position in the code 
window. The cursor must be on a line that 
contains code (place the code window in mixed 
mode if you are unsure) . The default function key 
assignment for BPX is F9. 

' Go to cursor line 

You can set a temporary break point at the cursor 
and go with the HERE command. The cursor must 
be on a line that contains code (place the code 
window in mixed mode if you are unsure) . The 
default function key assignment for HERE is F7 . 
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Scrolling the code window 

The code window can be scrolled only while the 
cursor is in the code window. The scrolling keys 
(UP arrow, DOWN arrow, PageUp and 
PageDown) are redefined while the cursor is in 
code window. When the cursor is in the code 
window the scrolling keys do the following: 
up — Scroll code window up one line 
down — Scroll code window down one 
pageup — Scroll code window up one window 
pageDn — Scroll code window down one 

window 



Note : 

jlhe code window must be visible for the EC command to work, 
Default Function Key: F6 



D 
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Locate current instruction 
Syntax: 

0- 

Comments : 

When the code window is visible, the . command makes the current source 
line or current instruction visible. 



D 
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5.8 Debugger Customization Commands 



D 

D 



Commands : 



PAUSE — Pause after each screen 

ALTKEY — Set alternate key sequence to 

invoke Soft-ICE 
FKEY — Show and edit function keys 

BASE — Set/display current radix 

CTRL-P — Toggle log session to printer 



D 



D 



Print-Screen — Print contents of screen 
PRN — Set printer output port 



D 
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PAUSE 

PAUSE — Pause after each screen 



[ 



JjSyntax : 

PAUSE [ON | OFF] 
Qcomments : 

PAUSE controls screen pause at the end of each page. If PAUSE is ON, you 
are prompted to press any key before information is scrolled off the 
jwindow. The prompt is displayed in the status line at the bottom of the 
window. 

•If no parameter is specified, the current state of PAUSE is displayed. 

The default is PAUSE mode ON. 

Example: 

PAUSE ON 

This command specifies that subsequent window 
display commands will cause the screen to wait for you 
to press a key before scrolling new information off the 
window. 



D 
D 

1 
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ALTKEY 

LTKEY — Set alternate key sequence to invoke Soft-ICE 



^Syntax : 



D 



ALTKEY [ALTletter] | [CTRLletter] | [SYSREQ] 
letter - Any letter (A - Z) 



Comments : 

The ALTKEY command allows the key sequence for popping up Soft-ICE to be 
changed. The key sequence be changed to CTRL + letter, ALT + letter, or 



pQccasionally you may be using a program that conflicts with the CTRL D key 
Lsequence that brings up the Soft-ICE window. One way to circumvent this 
possible problem is to use the ALTKEY command to change the key sequence. 
Another way is to add the SHIFT key to the current sequence. Soft-ICE does 
not respond to this key sequence and allows it to go through to your 
program. For example if a resident program you are using is brought up 
with the CTRL D key sequence, try using the key sequence CTRL SHIFT D to 
bring up your resident program. On some keyboards, you must press ALT and 
-the prtsc key simultaneously to generate a system request. Care must be 
taken so the screen is not printed accidentally. 

Dlf no parameter is specified, the current key sequence state is displayed. 



he default key sequence is CTRL D. 



D 
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U Example: 

ALTKEY ALT Z 

□This command specifies that the key sequence 
ALT Z will now be used to pop up the Soft-ICE 
window. 

FKEY 

Dfkey — Show and edit function keys 



pSyntax: 



FKEY [function-key-name string] 
function-key-name — Fl, F2... F12 

string — The string consists of any valid Soft-ICE 

commands and the special character 
A (caret) and ; (semicolon) . A A is 
placed in the string to make a 
command invisible. A ; is placed in 
the string to denote a carriage return. 



U 

D 

D 

D 

Comments : 

The FKEY command is used from the command line to assign a function key to 

Da command string. Function key can be assigned to any command string that 
can be typed into Soft-ICE. 

r|If no parameters are specified, then the current function key assignments 
[Jare displayed. 

To unassign a specified function key, use the FKEY command with these 
parameters: a function-key-name followed by a null string. 

The function keys can also be pre-initialized in the definition file S- 
ICE.DAT. For more information on function key definitions in the 
definition file, refer to section 6.4. 

Using carriage return symbols in a function key assignment string allows 
I you to assign a function key a series of commands. A carriage return is 



D 



represented by a ; (semicolon) . 
141 



If you put A (shift 6) in front of a function key definition, the 
["^subsequent command will be invisible. The command will function as normal, 
Ljbut all information displayed in the command window (including error 

messages) is suppressed. The invisible mode is useful when a command 

changes information in a window (code, register or data) but you do not 

want to clutter the command window, 

When a function key is made invisible with A , the function key can be used 
Fjin the middle of typing in other command without affecting their 
operation. For example, if you are using the default assignment for F2 , 
you can toggle the register window with F2 even if you are partially 
jjthrough typing in your next command. 



D 

Note : 

Soft-ICE now has a definition file named S-ICE.DAT. You can place function 
key assignments in this file so that function keys will be automatically 
assigned when Soft-ICE is loaded. The syntax for assigning a function key 

□in the configuration file is: 

When assigning function keys to a command string in S-ICE.DAT, the string 
must be enclosed in double quotes. 



PCommand line examples: 
FKEY F2 A WR; 

This example will assign the toggle register window 

□command to the F2 key. The A makes the function 
invisible, and the ; ends the function with a carriage 
return. The F2 key will toggle the register window 
on or off, and can even be evoked while typing in 
another command. 



D 
D 
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FKEY Fl "G CS:120; R; G CS:" 

This example shows that multiple commands can be 
assigned to a single function key and that partial 
commands can be assigned for the user to complete. 
After this command is entered, pressing the Fl key 
will cause the program to execute until location 
CS:120 is reached, display the registers, then start the 
G command for the user to complete. 



D 
□ 
D 
D 
D 



FKEY Fl WD 3;D DS:100; 

This example will assign a series of commands to the 
Fl key. The function is visible, and ends with a 
carriage return. The Fl key will make the data 
window three lines long and dump data starting at 
DS:100. 
S-ICE.DAT example: 

Fl = "WR;WD 2;WC 10;" 

If this line is placed in S-ICE.DAT, when Soft-ICE is 
loaded it will assign the string to the Fl key. When 
Fl is pressed while in Soft-ICE, it will toggle the 
register window, create a data window of length 2 and < 
code window of length 10. For more information about 
assigning function key definitions in S-ICE.DAT, refer 
to chapter 6. 



D 
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BASE 

BASE — Set/display current radix 
Syntax: 

BASE [10 | 16] 



Comments : 

rfThe BASE command sets the current radix to base 10 or base 16. Base 10 is 



U 



D .... 

of limited use in the narrow window because of window width limitations. 
It also limits the amount of information displayed in some commands in the 
Qtfide mode. 

When the current radix is base 10, all numbers and addresses typed into 

Gand displayed by Soft-ICE are in decimal, When the current radix is base 
16, all numbers and addresses typed into Soft-ICE are in hexadecimal 
except: 

* source line numbers 

* screen coordinates and sizes in the WIN command 



D 



These exceptions are always typed in and displayed as decimal numbers. 
Qrhe default radix is base 16. 

□Example : 
BASE 16 
This example sets the current radix to base 16. 



D 
D 
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CTRL-P 

jCTRL-P Toggle log session to printer 

Syntax: 
CTRL-P 



Comments : 

When the CTRL key followed by the P key is pressed, all subsequent 
information displayed in the command window is also sent to the printer 
*o turn the log to printer mode off, type CTRL followed by P again. 



w: 



hen you are sending a lot of information to the printer using CTRL-P, you 
may want to turn the PAUSE command OFF to allow information to scroll off 
]the window without pressing a key. 
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Print-Screen 



J 



D 



Print-Screen - Print contents of screen 
Syntax: 

Print-Screen 



Comments: 

Depressing the print-screen key does a screen dump to printer. All 
[Jinformation from the screen is sent the printer. 

If you wish to print the memory map or help information is usually much 
•faster to use CTRL-P than Print-Screen. This is because Print-Screen 
prints every character on the screen including borders., 



D 
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PRN 



RN Set printer output port 



jjSyntax : 



n 



PRN [LPTx | COMX] 

x — a decimal number between 1 and 4 



Comments : 

The PRN command allows you to send output from the CTRL-P and Print-Screen 
commands to a different printer port. 

If no parameters are supplied, PRN displays the currently assigned printer 
port. 

Example: 
PRN COM 1 

This command causes the CTRL-P and Print-Screen 
command output to go to the COM 1 port. 
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5.9 Screen Control Commands 



Commands : 

FLASH 
■i FLICK 

WATCHV 
J RS 
CLS 

ALT SCR 
WIN 



— Restore screen during P and T 

— Screen flicker reduction 

— Set watch video mode 

— Restore program screen 

— Clear window 

— Change to alternate screen 

— Change size of Soft-ICE window 
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FLASH 

JjFLASH — Restore screen during P and T 



:j 
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Syntax: 

FLASH [ON 



OFF] 



D 



omments : 

The FLASH command lets you specify whether the screen will be restored 
luring any Trace and Program step commands. If you specify that the screen 
is to be restored it is restored for the brief time period that the P or T 
command is executing. This feature is needed to debug sections of code 
that access video memory. 



If the P command executes across a call or an interrupt, the screen will 

E always be restored, because the routine being called may write to the 
screen. 

If no parameter is specified, the current state of FLASH is displayed. 
!rhe default is FLASH mode OFF. 



rExample: 
FLASH ON 

This command turns on FLASH mode. The screen will 
be restored during any subsequent P or T commands 



D 

; 
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FLICK 

FLICK — Screen flicker reduction 
Syntax : 

FLICK [ON | OFF] 



Comments : 

Certain types of video cards require waiting for horizontal or vertical 
retrace before outputting characters. If the video writes are made 
arbitrarily, flickering will appear while displaying characters. If 
flickering occurs on your screen while using the Soft-ICE window, you 
should turn FLICK on. 



With some EGA cards, colors will not be restored properly when you exit 
Jfrom Soft-ICE. This is a problem with virtualizing EGA video. The port 3 DA 
is a video port used for two purposes. The first is old CGA software 
polling 3 DA for hsync and vsync. This allows them to have flicker free 
output on some old CGA controller cards. The second is that it is used to 
reset a palette latch on EGA cards. Scft-ICE has an algorithm to avoid 
having to constantly watch this port, which would slow down old programs 
that think they are on a CGA. However, there can occasional be 
Lcircumstances where this algorithm does not work. If you are using Soft- 
ICE on an EGA screen and you notice that the colors are not 



D 
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estored 

correctly, then turn FLICK ON and Soft-ICE will watch the 3 DA port, fixing 
■the problem. 



: 



When FLICK mode is ON, screen update will be slower. 

jlf no parameter is specified, the current state of FLICK is displayed. 
T The default is FLICK mode OFF. 
150 



D 



Example: 
FLICK ON 

This command turns on FLICK mode. This causes 
Soft-ICE to wait for the horizontal or vertical retrace 
before outputting characters. 
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WATCHV 

WATCHV — Set watch video mode 



Syntax: 

y 

WATCHV [ON | OFF] 
Hcomments : 

The WATCHV command allows you to specify how Soft-ICE should watch the 
video ports. Normally, Soft-ICE only watches video ports after an INT 10 

[-[instruction has been executed that switches to a non-character video mode. 

[_Some programs do not use INT 10 to switch modes. In these cases, if WATCHV 
is OFF, Soft-ICE may have trouble saving and restoring the screen 
properly. Turning WATCHV ON will cause Soft-ICE to watch the video ports 

jjall the time. 

Turn WATCHV ON if you notice that Soft-ICE is not handling your screen 
properly, or if the cursor is not being restored properly. Turning WATCHV 
ON may have a performance impact in certain video modes. 

-If no parameter is specified, the current state of WATCHV is displayed. 

The default is WATCHV mode OFF. 

P 

Example: 

WATCHV ON 

This command turns on WATCHV mode. This causes 
Soft-ICE to watch additional video ports for the 
purpose of virtualization. 
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RS 



n 

RS — Restore program screen 



'Syntax : 



D 



RS 

P 

Comments : 

The RS command allows you to restore the program screen temporarily. The 
Soft-ICE window disappears until any key is pressed. 

This feature is useful when debugging graphic programs that update the 
screen frequently. When Soft-ICE is brought up, it returns to text mode. 
Using the RS command temporarily restores the graphics screen. 



D 
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Example: 
RS 
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CLS 



CLS — Clear window 



D 



yntax: 
CLS 



Comments : 

CThe CLS command clears the Soft-ICE window and moves the prompt and the 
cursor to the upper left-hand corner the window. 



D 



Example: 
CLS 



n 



154 

ALTSCR 

ALTSCR — Change to alternate screen 
Syntax : 

ALTSCR [ON | OFF] 



Comments : 

The ALTSCR command allows you to redirect the Soft-ICE output from your 
default screen to the alternate screen. This feature is useful, for 
instance, when you want to debug a graphics program without having to 
switch between the Soft-ICE window and the graphics display. 

ALTSCR requires the system to have two monitors attached. The alternate 

Donitor should be in a character mode, which is the default mode for 
monitors. 

The default is ALTSCR mode OFF. 

Example: 

ALTSCR ON 

□This command redirects screen output to the alternate 
monitor. 
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WIN 

DtflN — Change size of Soft-ICE window 
QSyntax: 



D 
D 
D 
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WIN [N [ W] [start-row length [start- column] ] 
N — When N is specified, the window will 

be set to the narrow width: 46 
characters . 

W — When W is specified, the window will 

be set to full screen width. 

start-row — Number from to 17 specifying row 

where window display starts. 

length — Number from 8 to 25 specifying how 

many lines tall you want the window 
to be. 

start-column — Column position of the left side of 

narrow window. The start-row and 
start-column specify the upper left 
hand corner of the narrow window. 
The start-column is ignored if applied 
to the wide window. 



Rcomments : 

The WIN command allows you to modify the width and height of the Soft-ICE 
display window. 

Jjlf no parameters are specified, this command toggles the window between 
wide and narrow screen display modes. 



Q 
I 



■If the WIN command is specified with only the N or the W parameter, the 
Window size will be changed to the requested width at the current height. 
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If the number of lines plus the starting row number is larger than 25, the 
window length goes to the bottom of the screen. 



The default is WIN mode narrow. 

C Examples: 
WIN N 4 9 30 

This command causes the window display to start at 
row 4 and column 30, and to be 9 rows tall and 4 6 
characters wide. 
WIN 

This command toggles the window display width from 

its current state (either wide or narrow) to the opposite 

state . 



D 
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WIN W 10 8 

This command causes the window display to start at 
row 10, and to be 8 rows tall and go the width of the 
screen. 
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L5.10 Symbol and Source Line Commands 



D 
D 
D 



Commands : 
SYM 

SYMLOC 
SRC 
■FILE 
SS 
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-- Display/set symbol 

— Relocate symbol base 

— Toggle between source, mixed and code 

— Change/display current source 

— Search current source file for string 



SYM 
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SYM — Display/set symbol 



□ 

D 
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Syntax: 



SYM [symbol-name [value]] 

symbol-name — A valid symbol name. The symbol 

name can end with an * (asterisk) . 
This allows searching if only the first 
part of the symbol name is known. 
The , (comma) character can be used 
as a wild card character in place of 
character in the symbol-name. 

value — This is a word value that is used if you 

want to set a symbol to a specific value, 



Comments : 

The SYM command allows displaying and setting of symbols. If SYM is 
entered with no parameters all symbols are displayed. The value of each 
ymbol is displayed next to the symbol name. 



-If a symbol name is specified with no value then the symbol name and value 
are displayed. If the symbol name was not found then nothing is displayed. 

The SYM command is often useful for finding a symbol name when you can 
only remember a portion of the name Two wild card methods are available 
for locating symbols. If symbol-name ends with an *, then all symbols that 
match the actual characters typed prior to the * will be displayed 
regardless of their ending characters. If a , is used in place of a 
specific character in symbol-name, that character is a wild card 
character. 

If value is specified, all symbols that match symbol-name are set to the 
value. All symbols have word values. 
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Examples: 
SYM F00* 

All symbols that start with F00 are displayed. 
SYM F00* 6000 

All symbols that start with FOO are given the value 
6000. 



D 
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SYMLOC 

SYMLOC — Relocate symbol base 
Syntax : 

SYMLOC segment -address 



Comments : 

The SYMLOC command relocates the segment components of all symbols 
relative to the specified segment address. This function is necessary when 
debugging loadable device drivers or other programs that can not be loaded 
directly with LDR.EXE. 



when relocating for a loadable device driver, use the value of the base 
address of the driver as found in the MAP command. When relocating for an 
. EXE program, the value is 10H greater than that found as the base in the 
MAP command. When relocating for a .COM program, use the base segment 
address that is found in the MAP command. 

n 

The MAP command will display at least two entries for each program. The 
first is typically the environment and the second is typically the 
program. The base address of the program is the relocation value. 

-Example: 

SYMLOC 1244 + 10 

This will relocate all segments in the symbol table 
relative to 1244. The + 10 is used to relocate a TSR 
that was originally a . EXE file. If it is a .COM file the 
+ 10 is not necessary. 
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SRC 

SRC — Toggle between source, mixed and code 
_Syntax: 

SRC [?] 



n 



Comments : 

The SRC command toggles between source mode, mixed mode and code mode in 
the code window. 

If SRC ? is entered, the current state is displayed. 

Example: 
SRC 

This command changes the current mode of the code 
window. If the mode was source, it becomes mixed, 
the mode was mixed, it becomes code. If the mode was 
code, it becomes source. 

JDef ault-Function Key: F3 
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FILE 

FILE — Change/ display current source file 



j~Syntax: 

FILE {file-name] 
rjcomments : 

L If a file-name is specified, that file becomes the current file and the 

start of the file is displayed in the code window. If no name is 
jjspecif ied, the name of the current source file (if any) is displayed. 

The FILE command is often useful when setting a break point on a line that 

as no associated public symbol. Use file to bring the desired file into 
the code window, use the SS command to locate the specific line, move the 
cursor the specific line, then type BPX to set the break point. 



Note: 

Only source files that have been loaded into extended memory with LDR.EXE 
are available with the FILE command. 

Example: 

FILE MAIN.C 

If MAIN.C had been loaded with LDR.EXE, this 
command brings it up in the code window starting with 
line 1. 



D 
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SS 

n 

[J3S — Search current source file for string 
Syntax: 



SS [line-number] [ ' string'] 
line-number — a decimal number 

string — a character string surrounded by quotes 

The quotes can be either single quotes 
or double quotes. 



D 

D 
D 

Comments : 

The SS command searches the current source file for the specified 

C character string. If there is a match, the line that the string was 
located in will be displayed as the top line in the code window. 

DThe search starts at the specified line number. If no line number is 
specified the search starts at the top line displayed in the code window. 

plf no parameters are specified, the search continues for the previously 
specified string. 

Note: 

The code window must be visible and in source mode before using the SS 
command . 



Example : 



ss l 'if (i = = 3) ' 

The current source file is searched starting at line 1 for 
the string 'if (i = = 3)'. The line containing the next 
occurrence of the string becomes the top line displayed 
in the code window. 
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SECTION III - Support Features 
CHAPTER 6 
Soft-ICE Initialization Options 

6.1 Introduction 

6.2 Loading from the DOS Prompt 

6.3 Loading Soft-ICE as a Loadable Device Driver 
6.3.1 Soft-ICE Loading Switches 

6.4 The Soft-ICE Initialization File S-ICE.DAT 

6.4.1 Configuration Options 

6.4.2 Function Key Assignments 

6.4.3 Initialization Command Sequence 



: 
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6.1 Introduction 



The Soft-ICE program file (S-ICE.EXE) can be loaded as a loadable device 
driver in CONFIG.SYS or as a program from the DOS command line. To get the 
-full power of Soft-ICE, it must be initially loaded as a device driver in 
CONFIG.SYS. However, there may be circumstances when you might want to run 
Soft-ICE from the DOS prompt or a batch file, such as: 



D 
D 
D 
D 
D 
D 
D 
D 

a 

D 



* You do not have extended memory in your system 
S 



D 



D 
D 



D 



oft-ICE can only load as a loadable device driver 
if you have extended memory. 

* You want to take up ZERO bytes of conventional 
memory. When loaded as a device driver, 
Soft-ICE occupies approximately 2K of 
conventional memory. 

* You only need to use Soft-ICE occasionally and 
there are no other programs using extended 
memory . 



In some cases you may need some of the features that require Soft-ICE to 
be loaded in CONFIG.SYS but do not want Soft-ICE to be resident all of the 

Dtime. In this case Soft-ICE can be loaded in CONFIG.SYS to reserve 
extended memory, and then disabled, by using the /UN switch, until Soft- 
ICE is required. See section 6.3.1 for more information about the /UN 
witch. 



6.2 Loading Soft-ICE from the DOS Prompt 



You can NOT enable all of Soft-ICE 's features when loading from the DOS 
prompt. If you will be using Soft-ICE as a stand-alone debugger, it is 
recommended you load Soft-ICE in the CONFIG.SYS file. 



D 

rr 
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o load Soft-ICE from the DOS prompt type: 
S-ICE 



D 



in systems with no extended memory present, Soft-ICE loads itself at the 
highest memory location possible. The memory used by Soft-ICE is then 
'mapped out', making it invisible to DOS programs. Since the total memory 

C [visible to DOS and its programs is less after Soft-ICE loads, it is 
recommended that you load Soft-ICE before any TSR's control programs. 



-jln systems with extended memory, you should only load Soft-ICE from the 
DOS prompt if you are not using extended memory for anything else (e.g., 
-VDISK, CACHE, HIMEM. . . ) . When you initially load Soft-ICE from the command 
line or from a batch file, Soft-ICE will prompt you with a warning 
^message. This warning message is just to remind you that Soft-ICE will 
.overwrite the highest portion of extended memory when it loads. You can 
suppress this warning prompt with the EXTENDED option in the Soft-ICE 
configuration file S-ICE. DAT. For more information about the EXTENDED 
option, see section 6.4.1. 



d 



6.3 Loading Soft-ICE as a Loadable Device Driver 



In order to use all of the Soft-ICE features, you must first load Soft-ICE 
as a loadable device driver in your CONFIG.SYS file. The features this 
Quakes possible are: 

* Coexisting with other software that uses extended 

□memory . 
Loading as a device driver allows Soft-ICE to 
manage extended memory so you can run Soft-ICE 
with programs that use extended memory, such 
VDISK, CACHE and HIMEM. 



D 
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Symbolic and source level debugging 

Loading as a device driver allows Soft-ICE to 
allocate an 



D 
D 
D 



extended memory buffer for symbols 
and source information. 

* Back trace ranges and the SNAP command 
Loading as a device driver allows Soft-ICE to 
allocate an extended memory buffer for a back 
trace buffer. This buffer is also used for the 
Soft-ICE SNAP command. 

* Enabling Soft-ICE' s EMM 4.0 capability 

* Running Soft-ICE with MagicCV or MagicCVW 

L Note : 

When loaded as a device driver in CONFIG.SYS, Soft-ICE allocates the 
Phighest portion of extended memory for itself and its associated 
L-components , so there can be no memory conflicts. S-ICE.EXE must be loaded 
in CONFIG.SYS before any other driver that allocates extended memory 
loaded (e.g., VDISK.SYS, RAMDRIVE. SYS) . Generally Soft-ICE works best if 
at is the first loadable device driver installed in CONFIG.SYS. 



o 



6.3.1 Soft-ICE Loading Switches 



One or more loading switches can follow S-ICE.EXE in CONFIG.SYS. These 
switches allow you to customize the way extended memory will be reserved 
by Soft-ICE. The switches all must begin with a / character. The loading 
switches are: 
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* /EXT XXXX — Informs S-ICE.EXE to reserve 

XXXX Kilobytes of extended memory for other 
DOS programs that use extended memory (e.g., 
VDISK, CACHE, HIMEM, . . . ) . If the /EXT 
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C switch is not present, then any extended memory not used by Soft-ICE and 
tits associated components will be left as standard extended memory, but 
the amount can not be guaranteed. The /EXT switch is useful because it is 
sometimes difficult to determine exactly how much memory being used by 
Soft-ICE and its associated components. Using the /EXT switch will 
guarantee a specified amount is available for other programs that use 
extended memory. 



D 
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/SYM XXXX — Informs S-ICE.EXE to reserve 
XXXX Kilobytes of extended memory for symbols 
and source usage. If XXXX is not specified, then 
all remaining extended memory is used for 
symbols. Enough memory must be allocated for 
your . SYM file and all source files. For more 
information about using symbols and source, see 
chapter 7. 

/TRA XXXX — Informs S-ICE.EXE to reserve 
XXXX Kilobytes of extended memory for a back 
trace history buffer. This buffer is used for back 
trace ranges and for the SNAP command. If 
XXXX is not specified, then 10K of extended 
memory is automatically reserved for the buffer. If 
you do not want any memory reserved for a back 
trace buffer, use /TRA 0. For more information 
about using back trace ranges, see chapter 9. 
/MCV XXX — Informs S-ICE.EXE to reserve 
XXX Kilobytes of extended memory for MagicCV 
or MagicCVW. The minimum amount of extended 



memory you can specify is 2 8 OK and the maximum 
is 620K. If XXX is not specified, S-ICE.EXE will 
reserve the remaining memory, between 2 8 OK and 
62 OK. See chapter 10 for more information about 
running Soft-ICE with MagicCV or MagicCVW. 
*/EMM XXXX — Informs S-ICE.EXE to turn 
XXXX Kilobytes of extended memory into EMM 



4.0 conforming expanded memory. If XXXX is 
specified, then all remaining memory is used as 
expanded. See chapter 8 for more information 
about expanded memory support. 
* /UN — Informs S-ICE.EXE to enter protected 

mode, reserve any needed extended memory, then 
exit protected mode and unload itself. This switch 
should be used when you are loading S-ICE.EXE 
as a loadable device driver, but you don't want 
your system to remain in protected mode. This 
switch will reserve memory for Soft-ICE, and you 
must execute S-ICE.EXE from the DOS prompt 
when you are ready to use Soft-ICE. 



Soft-ICE reserves extended memory in the following order, regardless of 
-the order the switches are specified: 



Reserve approximately 120K for S-ICE.EXE. 
Reserve memory for the /EXT switch if present. 
Reserve memory for the / SYM switch if present. 
Reserve memory for the /TRA switch if present. 

if it is not present, default to reserve 10K for 

the back trace buffer. 
Reserve mem 
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bry for the /MCV switch if present. 

Reserve memory for the /EMM switch if present. 



If available memory runs out while trying to reserve memory for a switch 
in the above sequence, then S-ICE.EXE does the following: 



D 
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1. The remaining extended memory is allocated to 

switch being processed when memory runs out. 

2. No memory will be reserved for the remaining 

switches. 
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Note: 

If the /MCV or /EMM switch is present, a additional 64K of extended memory 
is reserved for a DMA holding buffer. 



he switches can be placed in any order following DEVICE = S-ICE.EXE. 
example is: 



DEVICE = S-ICE.EXE /TRA50 /EMM 500 /SYM 2048 



GIf four megabytes of extended memory are available, this example will 
reserve approximately 12 OK for Soft-ICE, 2 megabytes for symbols, 5 OK for 
a back trace history buffer, 50 OK for expanded memory and leave 

D approximately 1.3 megabytes for other extended memory programs. Note that 
Soft-ICE will load into the highest portion of extended memory, leaving 
the remaining memory starting at 1000 00H (one megabyte mark) . 
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6.4 The Soft-ICE Initialization File S-ICE.DAT 



Soft-ICE has several load options. These options are specified by placing 
[-'special commands in an initialization file named S-ICE.DAT. 
[js~ICE.DAT is an ASCII text file that Soft-ICE parses at load time. This 

file can contain function key assignment an auto-start string and various 
^configuration options. The file can be created and edited with any DOS 
I [text editor. When loading Soft-ICE from the command line, S-ICE.DAT must 

be placed in the current directory or in a directory that is accessible 

through your current PATH. When Soft-ICE is loaded as a device driver in 
pCONFIG . SYS , S-ICE.DAT must be in the same directory where S-ICE.EXE is 
Ljlocated . 
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here are three categories of commands that can be included in the S- 
JCE.DAT initialization file: 

* Special configuration options 

* Function key assignments 

* Initialization command sequence 

6.4.1 Special Configuration Options 

Any of the following configuration options that are needed should each be 
placed on a separate line in the S-ICE.DAT file. 
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* COMPAQ — Compaq 3 86 and 386SX computer 
and some Compaq compatible computers 
(including computers containing Micronix 
motherboards) have 384K of non-contiguous 
extended memory. The COMPAQ option is 
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necessary if you want Soft-ICE to use this memory. 
Note that the COMPAQ option is the same as the 
/C command line parameter in Soft-ICE l.X. 

* NOLEDS — The NOLEDS option tells Soft-ICE 

not to set and clear the keyboard LEDs while the 
Soft-ICE window is up. On some keyboards the 
are timing problems that will cause Soft-ICE to 
lose synchronization with the keyboard. If 
Soft-ICE hangs when you are in the Soft-ICE 
window use this option. Note that the NOLEDS 
option is the same as the /L command line 
parameter in Soft-ICE l.X. 
* NOTVGA — The NOTVGA option allows 

Soft-ICE to run on BIOS compatible VGA cards. 
Many VGA cards are not compatible with IBM 
VGA at the hardware level. These cards support 
VGA at the BIOS level only. Use this switch if you 
have one of those video adapters. Note that the 
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NOTVGA option is the same as the /V command 
line parameter in Soft-ICE l.X. 

* EXTENDED — The EXTENDED option causes 

Soft-ICE to load directly into extended memory 
without prompting the user with a warning 
message. It should be used if you are loading 
Soft-ICE initially from the DOS prompt and do 
want to be prompted, and you know nothing else 
using extended memory. Note that the 
EXTENDED option is the same as the /E 
command line parameter in Soft-ICE l.X. 



6.4.2 Function Key Assignments 

One or more Soft-ICE commands can be assigned to any function key at load 
time. See the description of the FKEY command in section 5.8 (Debugger 
Customization Commands) for a description of assigning function keys from 
the Soft-ICE command line. 

i 

The syntax for assigning a function key name in S-ICE.DAT is : 
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function-key-name = "string" 

function-key-name — Fl, F2 . . . F12. 

string — The string may consist of any valid 

Soft-ICE commands and the special 
characters A and ; . A A is placed in 
the string to make a command 
invisible. A ; is placed in the string 
denote a carriage return. The string 
must be enclosed in double quotes. 
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An example function key assignment in S-ICE.DAT is: 
F12 = "D 100;" 
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This will assign the Soft-ICE dump command to function key 12. When F12 is 
pressed Soft-ICE will dump at offset 100H in the current data segment. The 
j~jsemi-colon following the 100 represents the ENTER key. 
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6.4.3 Initialization Command Sequence 



A sequence of commands can be automatically executed when Soft-ICE loads. 
This is useful for customizing Soft-ICE to meet your needs. For example, 

Cymi might set up windows and change the default hot key sequence, 
jrhe syntax for setting up an initialization command sequence in S-ICE.DAT 
is: 



D 
D 
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An example initialization command sequence in S-ICE.DAT is: 

INIT = "WIN; WR; WD 1; WC 12; ALTKEY CTRL X;" 

his example will put the Soft-ICE window in full screen mode, create a 
register window, create a data window one line long, create a code window 
12 lines long, and change the hot key sequence to CTRL X. 



INIT = "assignment-string" 

assignment string — The string consists of any valid 

Soft-ICE commands and the special 
characters A and ; . A A is placed in 
the string to make a command 
invisible. A; is placed in the string 
denote a carriage return. The string 
must be enclosed in double quotes. 



Sample S-ICE.DAT 

A sample S-ICE.DAT initialization file is included on the distribution 
diskette. This sample assigns the function keys 
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[jso they are used in a similar manner as the function keys in Microsoft's 
CodeView debugger. This sample S-ICE.DAT should also be used as is for the 
tutorial in chapter 3 . 
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Page 176 is blank 

LJ 

176 
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CHAPTER 7 



D Symbolic and Source Level Debugging 
7.1 Introduction 

7.2 Preparing for Symbolic or Source Debugging 

7.2.1 Preparing for Symbolic Debugging Only 

7.2.2 Preparing for Symbolic and Source 

Level Debugging 

7.3 Reserving Memory for Symbols and Source File 

7.4 Loading Programs and Symbol Files 

7 . 5 Debugging With Symbols 

7 . 6 Debugging With Source 
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H7 . 1 Introduction 

oft-ICE can load programs, symbol tables and source files for enhanced 
debugging. Symbolic debugging allows you to set break points and reference 

Rvariables with symbol names rather than specifying numeric addresses. 
Source level debugging allows you to step through your program at the 
source code level rather than assembly code level. 

~] 

Symbol and source line number information is extracted from the link map 
file. The link map must be compatible with Microsoft's linker version 3.60 
r-pr greater. 

Symbols and source files reside in extended memory. You must have 
sufficient extended memory for the symbols and source files. Source files 
are not paged from the disk as in many debuggers. This allows Soft-ICE to 
provide complete system debugging in source level, You can debug T&SR's 
interrupt routines and other systems level code at the source level. 

Note: 

You cannot use symbolic or source level debugging unless Soft-ICE has been 
loaded as a device driver in CONFIG.SYS. 

7.2 Preparing for Symbolic or Source Debugging 

Before debugging a program with symbols or source you must create a symbol 
file. This is a binary file that contains symbol and line number 
information in a format that Soft-ICE can understand. This file is created 
with the utility MSYM.EXE. MSYM.EXE reads in your link map to create a 
symbol file with the extension (.SYM). 



P 
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Preparing for Symbolic Debugging Only 



To prepare a program for symbolic debugging only, you must do the 
following steps: 
1. Com 



D 
D 



D 
D 
D 
D 



pile or assemble your program. 

2 . Link your program with the proper switches to create 
a .MAP file that contains a list of public symbols. 
If you are using Microsoft's linker, the /MA switch 
is the proper switch to use. This .MAP file must be 
identical to the .MAP file produced by Microsoft's 

linker, version 3.60 or greater. 

3. Create a.SYM file by running MSYM.EXE. The 
syntax for using MSYM.EXE is: 

MSYM program-name [.extension] 
If the extension is not supplied MSYM assumes the 
extension is. MAP. MSYM reads in a map file as in 
and writes out a symbol file as output. The symbol 
has the name program-name. SYM. 



Note: 

Before compiling or assembling your program you may want to make some 
additional symbols public. Only public symbols are supported with Soft-ICE 
symbolic debugging. The way to make a variable or a label public varies, 
depending upon which language you are using. 



In 8086 assembly language, simply use the PUBLIC directive followed by the 
locally defined symbols you wish to make public. For example: 

PUBLIC FOO, L00P1, STATUS 



In C language, all procedure names and static variables are defined 
outside a block are public. 
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For other languages, refer to your language manual for details. 
|j7.2.2 Preparing for Symbolic and Source Level Debugging 



Jo prepare a program for both symbolic and source debugging, you must do 



U 



the following steps: 
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Compile or assemble each module that you wish 
debug at the source level with the appropriate 
switch to put line number information into the 
object files. With Microsoft languages you can use 
either the /Zi or the /Zd switches. You may not 
want to do this with all files, because the combined 
file 
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sizes of the symbol file and all the source files 

compiled with these switches must fit into the 
amount of extended memory you have reserved 
with the /SYM loading switch in CONFIG.SYS. 

2 . Link your program with the proper switches to create 
a. MAP file that contains source line numbers and 
a list of public symbols. If you are using 
Microsoft's linker, the /LI and /MA switches are 
the proper switches to use. This .MAP file must be 
identical to the. MAP file produced by Microsoft's 
linker, version 3.60 or greater. 

3. Create a. SYM file by running MSYM.EXE. The 
syntax for using MSYM.EXE is: 
MSYM program-name [.extension] 

If the extension is not supplied MSYM assumes the 
extension is. MAP. MSYM reads in a map file as input 
and writes out a symbol file as output. The symbol file 
has the name program-name. SYM. 



□ 
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7 . 3 Reserving Memory for Symbols and Source Files 



D 



Before loading programs, symbol files and source files you must reserve 
extended memory for them. Extended memory is reserved when you load Soft- 
pICE in CONFIG.SYS. Before reserving extended memory you may want to add up 
[the file sizes of the .SYM file and all of the source files that you want 
to load. You must reserve at least this much extended memory. 
You must use the /SYM loading switch when loading S-ICE.EXE. A sample line 

Cin CONFIG.SYS for loading Soft-ICE and reserving space for symbols and 
ource files is: 



DEVICE - S-ICE.EXE /SYM 1024 

This example loads Soft-ICE into extended memory and reserves 1 megabyte 
of memory for symbols and source files. See section 6.3 (Loading Soft-ICE 
as a Loadable Device Driver 
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') for more details on reserving memory. 



7.4 Loading Programs and Symbol Files 



The Soft-ICE utility LDR.EXE is used for loading programs, symbol files 
and source files. For symbolically debugging application programs and T&SR 
programs you will typically use LDR.EXE to load the program, symbols and 
source files in one step. For debugging loadable device drivers, ROMs and 
-pther system components you will typically use LDR.EXE to load the symbol 
file and source files only. 
The syntax for LDR.EXE is: 

LDR program-name | program-name . SYM | 

program-name . extension 
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~7.4.1 Loading Program, Symbols and Source 

To load your program, symbols and source files in one step, you must use 
LDR.EXE in the form: 

LDR program-name 



D 

D 



Notice that program-name does not have a file extension. If no file 
extension is supplied, then LDR.EXE will do the following: 

1. Load program-name . SYM into extended memory 

2. Load source files into extended memory. This step 
is done only if source records exist in the . SYM file. 

3 . Load program-name . EXE into memory at the 
location it would have loaded if it had been loaded 
directly from the DOS prompt. 

4 . Bring up Soft-ICE with the instruction pointer at 
first instruction of your program. If it is a C 
program and source is loaded for the file 
containin 
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g , _MAIN, then the source for that file 

will be visible in the code window. 



7.4.2 Loading Only Symbols and Source Files 



If you wish to load only symbols and source files (for debugging a 
loadable device driver for example) you must use LDR.EXE in the form: 



D 



LDR program-name. SYM 



Notice that the. SYM extension is specified. This will load the .SYM file 
and source files into extended memory. When symbols are loaded by this 
Rnethod your program or device driver symbols are assumed to be referenced 
Lferom 0:0. Since this is rarely the case you will need to use the Soft-ICE 
command SYMLOC to locate the symbols. See 
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Gthe description of the SYMLOC command in section 5.10 for a complete 
description. An example of loading a symbol file called DRIVER. SYM is: 



D7.4. 



LDR DRIVER. SYM 

3 Loading a Program With No Symbols or Source 



To load a program file without loading the associated symbol file you must 



use LDR.EXE in the form: 



LDR program-name. extension 



[■Notice that the file extension is present. Typically the file extension 

will be. EXE or.COM. When a file extension specified LDR.EXE will load the 
["program and bring up Soft-ICE with the instruction pointer at the first 
instruction of the program. An example of loading a program with symbols 
and source is: 

D 



LDR TEST. EXE 



Notes: 

LDR.EXE saves a copy of the interrupt vector table automatically when it 
loads your program. This is equivalent to doing a VECS S command. If you 
are going to exit your program before it runs to completion, you can do an 
EXIT R to exit the program and restore the interrupt vector table. 
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Using LDR.EXE to load only the program-name.EXE is often useful for 
restarting your program while in the middle of a source level debugging 
'session. To restart, the EXIT R command to abort the current session. Then 
use LDR.EXE to reload your. EXE file. The symbols: source do not have to be 
loaded since they remain in extended memory. 
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If LDR.EXE gives you the message "Out of space loading symbol 
information" , this means that you did not reserve enough extended memory 
with the /SYM loading switch in CONFIG.SYS. 

Hlf LDR.EXE does not find your source files on the same directory as the 
program you are loading, LDR.EXE will prompt you for the path names where 
it can find the source files. If you have source files on several 
directories or are loading a program frequently this becomes cumbersome. 



D 



You can eliminate the need for prompting by using the DOS environment 
variable SRC. LDR.EXE uses this environment variable to find source files 
before prompting the user. The syntax for setting the environment variable 



SET SRC = directory ; directory; ... /directory 

Each of the specified directories will be searched before the user is 
■prompted. 



Limitations: 

Soft-ICE supports symbols for only one program at a time. If you load a 

new .SYM file, the existing one is overwritten. 
L'soft-ICE does not follow overlays or Microsoft Windows segment movement. 

Soft-ICE recognizes public symbols and line numbers only. It does not 
i-support local variables. 



7 . 5 Debugging With Symbols 
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prompt is: 




baded your program and.SYM file you can begin debugging 

your program symbolically. In general a symbol can be used in any command 
in place of an address. 

J 
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Symbols are also used by several Soft-ICE commands when addresses are 
displayed. For example, the U command displays symbol names of labels and 
procedures as it encounters them. 

there are two commands that are helpful when you are symbolically 
debugging: 

* SYM — Use the SYM command to get a listing of 
symbol names and values, or to change the value 
a symbol. 

* SYMLOC — Use the SYMLOC command to 
relocate the base of all of your symbols. You 
would need to use the SYMLOC command when: 

1. Loading symbols for a loadable device driver 

2. Loading symbols for a T&SR that has already 
been loaded 

3 . Your program moves itself to a location other 
than its original location. 

See section 5. 10 for a complete description of these commands. 
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7 . 6 Debugging With Source 

When source files are loaded, Soft-ICE allows you to view and step through 
L your source code as you are debugging. Soft-ICE offers two different modes 
of source level debugging: mixed mode and source mode. Use the SRC command 

Dto switch between modes, 
taixed mode shows source lines and the assembly language produced by those 
source lines intermixed on the display. Mixed mode is useful when you must 
r-debug at the assembly level, but use the source lines for reference. Mixed 



U- 



mode is allowed whether the code window visible or not. 
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-Source mode strictly shows source lines on the display. Source level 
debugging requires the code window to be visible. 

1 ... 

^7.6.1 Using Line Numbers 

Line numbers can be used in place of addresses in several commands. To 
differentiate a line number from an actual address, place a . (period) in 
'front of the number. For example, to set an execution break point at 
source line 45 type: 



BPX .450 

7.6.2 Using Source Mode in the Code Window 



D 
[ 

The code window must be visible to enter source mode. If not visible, use 
the WC command to make it visible. Once you are in source mode you can use 
Soft-ICE commands switch to a different source file, view source at any 
location in the f 
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ile, scroll through the file, search for strings in the 
file, and set break points in the file. For a complete description of the 
pfollowing commands see their command descriptions in chapters 4 and 5. The 
following list is a brief overview of commands that are useful when 
debugging source code: 

* Make the code window visible (if it is not already) 
with the WC command. 

* Toggle between source, mixed, and code modes 
with the SRC command. To toggle modes enter: 

SRC 
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* Place a source file in the code window (if it is n@ 

already) with the FILE command. For example 
change from the current file to file MAIN.C enter: 

FILE MAIN.C 

* Display source at a specific location within the 

source file with the U command. To change the 
view to a specific line number or memory address 
use the U command. You can specify actual 
addresses or line numbers as a parameter to the 
command. For example, to view source in the 
code window starting at source line 450 enter: 

U .450 



Locate the current instruction in the code wind© 

with the . (period) command. 
Search for a specific character string with the S@ 

command. For example, to search for the string 

"Hello World" starting at line 100 in the current 

source file enter: 

SS 100 "Hello World" 

Move the cursor to the code window (if it is not 

already) with the EC command. 
Scroll the source with the keys up, down, 

PaqeUp, PageDn. 
Set point-and-shoot break points with the BPX 

command. Simply place the cursor on the source 

line that you wish to break on, then enter: 

BPX 
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□ Expanded Memory Support 
8 . 1 Introduction 

8.2 Configuring the EMM Environment 

□8.2.1 Default EMM Pages 
8.2.2 Customizing the EMM Page Map 
8.2.2.1 Including and Excluding Areas from EMM 

□8 . 3 Other EMM Features 
8.3.1 Increasing Conventional Memory 
8.3.2 Automatic Page Frame Locating 
8 . 4 EMM Debugging 
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8 . 1 Introduction 



Soft-ICE has an expanded memory manager built into its kernel. The Soft- 

nlCE expanded memory manager supports the Lotus-Intel-Microsof t 4 . 
specification. This Soft-ICE feature is useful if you are using programs 
that support the EMM specification, or if you must backfill your 
conventional memory to extend your conventional memory to 64 OK or more. 

Q>ther 386 control programs that provide EMM capability (such as QEMM or 
386-to-the-MAX) will not co-exist with Soft-ICE. If you are using those 
programs for EMM capability or backfilling, you can use the Soft-ICE EMM 
manager in their place. 



1 



Enabling EMM capability in Soft-ICE involves the following steps: 

1. Configure the expanded memory environment 
with the utility EMMSETUP.EXE. This utility 
modifies S-ICE.EXE with the desired EMM page 
map. 

2. Add the /EMM switch to your S-ICE.EXE line 
CONFIG.SYS. This reserves a portion of 
extended memory for expanded memory. An 
example line in CONFIG.SYS that reserves 
memory for EMM is: 

DEVICE = S-ICE.EXE /EMM 2048 
This will reserve 2 megabytes of extended memory 
for EMM use. See section 6.3 (Loading Soft-ICE 
as a Loadable Device Driver) for details of 
installing Soft-ICE in CONFIG.SYS. 
3. Reboot your system. 
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8.2 Configuring The EMM Environment 



[ 



Before installing S-ICE.EXE with the /EMM switch in CONFIG.SYS file, you 
may have to run EMMSETUP.EXE to configure the EMM 4 . environment . This 
configuration process allows you to select which portions of memory you 
would like to make available as EMM 4.0 pages. Running EMMSETUP.EXE is 
highly recommended if you are using programs that take full advantage of 
the EMM 4.0 specification. 



8.2.1 Default EMM Pages 

By default, S-ICE.EXE with the /EMM switch is pre-conf igured to allow EMM 
4.0 pages in the following areas: 
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* The lower 64 OK (except for the 1st 64K) 

* 64K starting at DDH 
¥ou may want to reconfigure for the following reasons: 

* You may have a device such as a network that i 
the DO00H area of memory. 

* You may want to fill more holes above 64 OK with 
EMM pages. This will increase performance and 
usability of programs like Microsoft Windows. To 
get maximum performance from Microsoft 
Windows you should fill every available page with 
expanded memory. 

8.2.2 Customizing the EMM Page Map 
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To configure the EMM map you must use the utility EMMSETUP . EXE . 
EMMSETUP . EXE allows the page map to be altered, then modifies S-ICE.EXE 
with the changes. 
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EMMSETUP makes its best guess on automatically configuring the EMM map. 
EMMSETUP will try to fill much of the address space as possible with 
mappable pages while working around video cards and ROMS. If its guess is 
not good enough or not to your liking you can override it. Overriding may 
be necessary if you have a network, a special video adapter or a memory- 
mapped option adapter. 
To configure the EMM map enter: 
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EMMSETUP 



J 



EMMSETUP displays a matrix of 16K memory pages available in the lower 1 
["megabyte region. The matrix is divided into 16 columns each representing 
[J64K (from to 10000H) . There are 4 rows representing the four 16K pages 

in each 64K region. 

pEach block of the matrix can contain an E, X, R or V. Blocks that contain 
Man E are available as EMM pages; blocks that contain an X are not. Blocks 
that contain an R are memory areas that have been identified by EMMSETUP 
as ROM areas. You can override these areas with an E if desired, however, 
this should only be done if the ROM is never accessed. Blocks that contain 
V are identified as video memory. We have made worst case assumptions on 
video memory. Your particular video card may not take up as much as we 
have 'guessed'. You can override the memory blocks that contain 
unnecessary V's if desired. 

Hlf you are satisfied with EMMSETUP 's guesses, press the F10 key and S- 
i-TCE.EXE will be modified with these parameters. You must reboot before any 
changes made to S-ICE.EXE will take effect. If you wish to override 
EMMSETUP 's guesses, do so at this time. 
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1 Including and Excluding Areas from EMM 



8.2.2. 



To include an area as EMM 4.0 memory simply guide the cursor to the 
desired block, then type E. Conversely, to exclude an area from EMM 4.0 
■memory, guide the cursor to the block and type X. When you are satisfied 
with your changes, press F10 to exit the program. All changes are 
^automatically stored in the S-ICE.EXE file. If you wish to exit without 



n 

modifying S-ICE.EXE press ESC. You must reboot before any changes made to 
S-ICE.EXE will take effect. 

Dwhen including upper memory blocks keep in mind the following: 
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* CGA occupies from B800H to COOOH. 

* MDA occupies from BOOOH to B100H. 

* Most Hercules cards occupy from B000 to COOOH. 

* EGA occupies from AOOOH to COOOH and from 
COOOH to C400H. 

* VGA (mother board) occupies from AOOOH to 
COOOH. 

* VGA (option card) occupies from AOOOH to 
COOOH and COOOH to C800H. 

* PS/2 System ROM occupies from EOOOH to 
10000H. 

* PS/2 ESDI ROM occupies from CCOOH to DOOOH 

* Most AT Compatible Roms occupy from FOOOH to 
10000H. 

* Compaq systems, Micronix motherboard systems, 
and most Chips and Technologies motherboard 
systems move the EGA/ VGA ROM to EOOOH 
However they still occupy the COOOH region as 
well . 

* Token Ring Networks usually occupy from CCOOH 
to EOOOH. 

* Many Networks occupy memory regions in the 
DOOOH area. 

;The above guidelines are for 'generic' devices, Many implementations by 
different computer vendors and 
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adapter card vendors will vary. 
3 Other EMM Features 



a. 



pS-ICE.EXE with the /EMM switch has two features that are automatically 
enabled depending on your system configuration. These features are 
backfilling and relocating the page frame. 

^8.3.1 Increasing Conventional Memory 



System memory will automatically be backfilled up to the first non- 
Lmappable page. This means it starts looking at contiguous E's at location 
1000, and continues until it finds the first non-contiguous E. If the 
contiguous E's go beyond the amount of your system's base memory, memory 
will backfilled up to the first R, V, or X that is found. 

The benefit of backfilling is that you can increase the amount of usable 
system memory to greater than 640K. The backfilled memory is available 
within DOS. If you do not want memory backfilled, use EMMSETUP to make 
page non-mappable (X) at the point you wish system memory to end. 

~| 
Note : 

Monochrome-only systems (MDA) can backfill up to BOOOH to add an 
^-additional 64K to conventional memory CGA systems can be backfilled up to 
B8 00, adding an additional 9 6K to conventional memory. EGA and VGA systems 
can be backfilled only if no graphics programs will be run. You can 
backfill an EGA or a VGA system up to B800:0 if no graphics programs will 
jjbe run. 

Warning: 

If memory is backfilled, DO NOT UNLOAD Soft-ICE. Doing so will cause your 



system to crash. 
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8.3.2 Automatic Page Frame Locating 



Vost EMM-knowledgeable programs require a 64K page frame that is not used 
as normal DOS memory. This is normally located above the video device 
area. However in some systems there is no 64K contiguous region to place 
|,the page frame. In these instances S-ICE.EXE 'steals' top 4 mappable pages 
Lof lower memory. The net result that lower DOS memory shrinks by 64K. 

|~8 . 4 EMM Debugging 

A range break point or a break point on memory that is in an EMM mappable 
j-area will stay at that address no matter which EMM page is mapped in. 
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When debugging EMM programs, the EMMMAP command may also be very useful 
See section 5.6 for more information. 



(The D, E, S, F, and C commands can be used to view or modify any allocated 
EMM handle page. The page does not have to be currently mapped in. The 

n syntax of these commands is similar to that of the commands when being 
used for non-EMM pages, except for the following: 
* In the D, E, S, and F commands, the address 

portion of the command must be specified in the 
following way: 
Hhandle# Ppage# offset 

where handle is a number specifying which EMM 
handle to use, page is a number specifying which 
EMM page to use, and offset is a number from to 
4000H, specifying the 
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offset from the beginning 
the page. 
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Example: 
DB HI P3 

This command will dump bytes from page 3 of 
handle l, starting at offset 0. 

* The C command must be specified in the following 
way: 

C Hhandle# Ppage# offsetl Llength offset2 
where handle and page are the same as above, 
offsetl is a number from to 4000H, specifying the 
offset from the beginning of the page, where the 
first data block to be compared is located. offset2 is 
a number from to 4 000H, specifying the offset 
from the beginning of the page, where the second 
data block to be compared is located. 
Example: 

C H2 P4 00 L10 1000 

This command will compare the first 10 bytes of 
memory located at offset of page 4 of handle 2 
with the first 10 bytes of memory located at offset 
1000 of page 4 of handle 2. 



Note: 

Subsequent uses of the D, E, S, F, and C commands will continue to use the 
handle and page last specified. To get back to conventional memory, use 
one of the above commands with a segment specified in the address field, 
for example: 
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D 0:0 
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Back Trace Ranges 

9 . 1 Introduction 

9.2 Using Back Trace Ranges 

9.3 Special Notes 
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9 . 1 Introduction 



Soft-ICE can collect instruction information in a back trace history- 
buffer as your program executes. These instructions can then be displayed 
after a bug has occurred. This allows you to go back and retrace a 
program's action to determine the actual flow of instructions preceding a 
pbreak point. 

Instruction information is collected on accesses within a specified 
address range, rather than system wide. The ranges can be from 1 byte to 1 
megabyte, so if desired , complete system information can be obtained. 

sing specific ranges rather than collecting all instructions is useful 
for two reasons: 
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nSoft-ICE has two methods of utilizing the instructions in the back trace 
history buffer: 



The back trace history buffer is not cluttered by 
extraneous information that you are not interested 
in. For example, you may not be interested in 
interrupt activity and execution within MSDOS. 

Back trace ranges degrade system performance while 
they are active. By limiting the range to an area 
that you are interested in, you can improve system 
performance greatly. 
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The SHOW command allows you to display 

instructions from the back trace history buffer. 
You must specify how many instructions you wish 
to go back in the buffer. 

The TRACE command allows you to go back and 

replay instructions from the back trace history 
buffer, This way you can see the instruction flow 
within the context of the surrounding program 
code or source code. 
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9.2 Using Back Trace Ranges 
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use back trace ranges you must do the following: 
1. Allocate a back trace history buffer of the desired 
size by inserting the /TRA switch on the 
S-ICE.EXE line in CONFIG.SYS. For example, 
to create a back trace buffer of 10 OK you might 
have the following line in your CONFIG.SYS file: 
DEVICE = S-ICE.EXE 100 

A back trace history buffer of 10K is allocated by 
default. If this is suitable for your needs you do not 
have to allocate a larger buffer. 
The history buffer size is only limited by the 
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amount of extended memory available. 

2 . Enable back trace ranges by creating a memory range 

break point with the T or TW verb. For example: 
BPR 1000:0 2000:0 T 

The T and TW verbs do not cause break points 
instead they log instruction information that can be 
displayed later with the SHOW or TRACE 
commands . 

3. Set any other break points if desired. 

4. Exit from Soft-ICE with the X command. 

5. After a break point has occurred, or you have 

popped Soft-ICE up with the hot key, you can 
display instructions in the buffer with the SHOW 
command. For example, to go back 50 instructions 
in the buffer and display instructions type: 
SHOW 50 
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6. To replay a series of instructions you must first 
enter trace simulation mode with the TRACE 
command. To begin replaying the sequence of 
instructions starting back 50 in the buffer type: 

TRACE 50 

7. After you have entered trace simulation mode, you 
can trace through the sequence of instructions by 
using the XT, XP, or XG commands. This allows 
you to re-enact the program flow. For example, 
you can single step through the sequence of 
instructions in the buffer, starting at the instruction 
specified by the TRACE command, by typing: 

XT 
XT 



XT 

The XT command single steps through the back 
trace history buffer. The XP command program 
steps through the back trace history buffer. The 
XG command goes to an address in the back trace 
history buffer. 

To exit from trace simulation mode type: 
TRACE OFF 

To reset the back trace history buffer, use the X 
command . 



9.3 Special Notes 

While in trace simulation mode, most Soft-ICE commands work as normal, 
including displaying the memory map, and displaying and editing data. The 
exceptions are: 



r 



1. Register information is not logged in the back trace 



history buffer, so the register values do not change 
as you trace through the buffer, except for CS and 
IP. 

Commands that normally exit from Soft-ICE do not 
work while in trace simulation mode. These are X, 
T, P, G, EXIT. 
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^~As you peruse instructions from the back trace history buffer with the 
r SHOW and TRACE commands, you may notice peculiarities in instruction 

execution. These are caused by jumps in and out of the specified range. 
L-These usually occur at jumps, calls, returns and entry points. 
When you have a hang problem or other difficult bug that requires back 

Brace ranges, you must often use very large ranges in order to narrow the 
cope of the problem. Once you have a better idea of the specific problem 
area, you go to smaller ranges. 

[Large back trace ranges are often very slow. When using large ranges you 
are usually trying to get a general idea where the problem is. Soft-ICE 
has a special 'COARSE' mode for doing large ranges. This speeds up the 

[ranges a factor of three or more, but limits the amount of instructions in 

Lthe history buffer. 

pCoarse mode only collects instructions that do a memory write within the 
specified range. As you are replaying instructions with trace simulation 
mode after a 'coarse' range you will notice that the flow skips around 
rather than sequentially executing instructions. 
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D Coarse ranges work best for large ranges and tend to be less effective for 
small ranges. 

rpo enable a 'coarse' back trace range, use the BPR command with the TW 
[jverb instead of the T verb. For example: 

BPR 1000:0 2000:0 TW 
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For further information on back trace ranges see the command descriptions 
for: 



SHOW, TRACE, XT, XP, XG, XRSET, BPR 
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10.1 

MagicCV allows you to run Microsoft's CodeView in less than 8K of 
conventional memory on your 803 86 machine. 

MagicCVW allows you to run Microsoft's CodeView for Windows in less than 
8K of conventional memory on your 8038 6 machine. 

Using Soft-ICE in combination with MagicCV or MagicCVW allows you to have 
|]the power of Soft-ICE while still having the convenience of using the 
CodeView product that you are familiar with. 



CHAPTER 10 

Using Soft-ICE with MagicCV or MagicCVW 

10.1 Introduction 

10.2 Running Soft-ICE with MagicCV or MagicCVW 

10.3 Special Considerations 

10.4 The Soft-ICE ACTION Command 
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Introduction 



In the rest of this chapter, statements about MCV will apply to both 
MagicCV and MagicCVW, and statements about CV will apply to both CodeView 
and CodeView for Windows. 

j 10.2 Running Soft-ICE with MagicCV or MagicCVW 

To use Soft-ICE 2.0 and MCV together, you must install S-ICE.EXE as a 

D loadable device driver. S-ICE.EXE comes on the Soft-ICE diskette. S- 
CE.EXE replaces NUMEGA. SYS in CONFIG.SYS. Use the /MCV, /EMM, and the 
/EXT switches as if using MagicCV or MagicCVW alone. There are additional 

□switches that you may want to use for Soft-ICE. Refer to chapter 6 for 
information about these switches. 

To run MagicCV or MagicCVW after Soft-ICE has been loaded, refer to your 
MagicCV or MagicCVW manual. 

Notes: 

^MagicCVW requires Soft-ICE version 2.00 or greater. 

MagicCV requires Soft-ICE version 1.02 or greater. The S-ICE.SYS and 
NUMEGA. SYS drivers were shipped with some versions of Soft-ICE. The S-ICE 
and NUMEGA 



204 



drivers must be replaced by S-ICE.EXE before you can run MagicCV and Soft- 
ICE 2.0 together. 

10.3 Special Considerations 

Two Virtual Machines 

[I 

When you are using both Soft-ICE and MCV together, you must keep m mind 
that CV is in a separate virtual machine from the target environment. You 
Pcan pop Soft-ICE up from either virtual machine, i.e., when CV is running, 
or when the target program is running. 



if you pop Soft-ICE up while the target program is running everything 
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works as defined in the Soft-ICE manual. If you pop Soft-ICE up while CV 
is running (typically done to break points) , you must keep a few points 
mind: 

* The registers are those of CV and they CAN NOT 
be changed. 

* For convenience, the Soft-ICE MAP command 
displays the memory map of the target program 
virtual machine, not the memory map of the CV 
virtual machine. The highlighted area in the 
memory map may not be correct. 

* Any display or modification of memory occurs in 
the target program's virtual machine. 

* You have no visibility into the CV virtual machine 
except for the display of register values. 
Remember that when popping up the Soft-ICE 
window while CV is active, the register values are 
those of CV and should not be modified. 

* Instruction and program tracing is disabled from 
the Soft-ICE window when CV is active. This is to 
prevent confusi 
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on, because a trace would actually 

step through CV, not through the target program, 
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If you attempt to do a Soft-ICE Trace (T) or 

Program Step (P) command while CV is active, 

you will get the warning message: "Function 

not available in CV virtual machine." 

To trace through your target program code instead, 

you can do one of two options: 

* Use the CV trace command. To do this, exit 

the Soft-ICE window using the Soft-ICE X 
command, then do one or more CV traces to 
step through the target program. 

* Use Soft-ICE to go to the target program 

address, then use the Soft-ICE T or P 
commands to step through your target 
program. To do this, exit the Soft-ICE window 
with the Soft-ICE X command, then press the 
'F3' key until CV is in 'mixed mode'. This 
allows you to see both the source lines and the 
instruction addresses. Pop up Soft-ICE. If the 
Soft-ICE window is not already in narrow 
mode, use the Soft-ICE WIN command to 
change the window size. Move the Soft-ICE 
window so you can see the instruction 
addresses on the left side of the screen. Now 
you can use the Soft-ICE G command to go to 
one of the addresses. Be sure to type in the full 
address, including the segment and the offset. 
Then enter 'G' in the CV window. At this 
point, CV is not active, so you can use the 
Soft-ICE T or P commands to step through t 
target program. 

CodeView' s SHELL command 



If you run the DOS shell from within the CodeView virtual machine, the DOS 
"'shell is part of the virtual machine. Because of this, you should not run 
Jany TSRs when you are in the DOS shell. If you do, when you exit CodeView 

the TSRs will disappear along with the virtual machine. This is 
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dangerous, because any interrupt vectors that were not restored could hang 
your machine. 

CV's /R switch 

Lsoft-ICE takes advantage of many of the 8 038 6 features including the 8 0386 
debug registers. This means that the debug registers are not available for 

-CV, so you cannot use the CV /R switch when running with Soft-ICE. If you 
do use the /R switch, Soft-ICE gives you a general protection error. At 
this point, you can press "C" to continue, then rerun CV without the /R 
switch, and use the Soft-ICE break points. 

P • ■ 

urhe CV /R switch works when you are running MCV without Soft-ICE. 



p. 4 The Soft-ICE ACTION Command 



D 

The ACTION command allows three different methods activating CV from a 
Soft-ICE break point. The best choice of action is ACTION NMI . If you 
experience any problems with ACTION set to NMI (usually because an adapter 
card in your system is using NMI) , use ACTION INT1. 
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SECTION III - Advanced Topics 
CHAPTER 11 

Advanced Features 

11.1 Using Soft-ICE with other Debuggers 

11.1.1 Debuggers that Use DOS 

11.1.2 ACTION Command with other Debuggers 

11.1.3 Special Considerations 

11.1.4 Using Soft-ICE with CODEVIEW 

11.1.5 Debuggers that Use 80386 Break Point 

Registers 

11.2 User-Qualified Break Points 
11.2.1 Example of a User-Qualified Break Point 

11.3 The Window in Graphics Mode 

11.4 Expanded Memory Debugging Features 

11.5 Extended Memory Debugging Features 
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11.1 Using Soft-ICE with other Debuggers 



Soft-ICE was designed to work well with other debuggers. Each debugger 
offers different features, and therefore can require special treatment. 
This section will describe some ways to use several debuggers effectively 



11.1.1 Debuggers that Use DOS 

GMany debuggers use DOS and ROM BIOS to perform their display and keyboard 
I/O. Special consideration must be taken when using these debuggers with 
Soft-ICE (e.g., DEBUG, SYMDEB, and CODEVIEW), because DOS and ROM BIOS are 
not fully re-entrant. If a break point occurs while code is executing in 
DOS or BIOS, a re-entrancy problem can occur. 

Soft-ICE provides optional re-entrancy warning, which is activated with 
the WARN command. When WARN mode is on, Soft-ICE checks for DOS or ROM 
LfilOS re-entrancy before generating the ACTION that wakes up the host 
debugger. When a re-entrancy problem is detected, Soft-ICE displays a 
warning message and offers you the choice of continuing to e 

LI 
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xecute the 

code or returning to Soft-ICE. 

Note that Soft-ICE itself does not use DOS or ROM BIOS calls in its 
debugging commands. This means that you can use Soft-ICE any time, without 
j~the worry of re-entrancy problems. 

For more information on the WARN command, see section 5.4. 

ljLl.1.2 ACTION Command with other Debuggers 

Different debuggers use different methods of activation For a description 
bf these methods see section 13.1. 



D 



210 



f you want to return to your debugger after a break point reached, you 
ust change the ACTION (see section 5.4) to work with your debugger. 
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•In most cases, the action that should be taken after a break point is 
reached is INT3. For instance, DEBUG and SYMDEB will work best with ACTION 
set to INT3. 



If INT3 doesn't work with your debugger, try INT1 or NMI. CODEVIEW works 
best with ACTION set to NMI. 

11.1.3 Special Considerations 



Pwhen a break point is set, you must be careful not to set off the break 

Lpoint unintentionally. For instance, if you set a memory break point at 
0:0, then use your debugger to dump memory location 0:0, Soft-ICE will be 

[-[triggered. If ACTION is set to go to your debugger, then your debugger 
will be triggered by itself. Since some debuggers cannot be re-entrant, 
this could be a fatal problem. This problem can also occur with other 

^debugging functions, such as editing or unassembling. 

-For this reason, it is a good practice to disable the Soft-ICE break 
points once Soft-ICE has helped you get to the point where you want to 
*iook around with your debugger. 
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11.1.4 Using Soft-ICE with CODEVIEW 



Soft-ICE works best with CODEVIEW when CODEVIEW is either in Assembler 
mode or Mixed mode. When CODEVIEW is in Source mode with higher-level 
languages it does not always break correctly. 

It is always best to use ACTION NMI when you want Soft-ICE to wake up 
CODEVIEW. 
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11.1.5 Debuggers that Use 8038 6 Break Point Registers 



The 803 86 has 4 break point registers that are available for use by 
debuggers. Soft-ICE uses these for its memory byte, word and double word 
break points. If the debugger you are using Soft-ICE with uses these debug 

[~jregisters there will be a conflict. There are two ways to handle this 

Lproblem. 



1. Disable the use of 80386 break point registers in the 
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debugger you are using Soft-ICE with. Check the 
documentation of your other debugger for a 
description of how to do this. 
2. Some debuggers automatically use the break point 

registers if they detect an 80386 processor with no 
method of turning them off (some versions of 
SYMDEB do this) . For these debuggers do the 
following: 

* Bring up the Soft-ICE window before you start 
the other debugger. 

* Turn on Soft-ICE' s break mode with the 
BREAK command (you may want to do this in 
the INIT statement of S-ICE.DAT if you are 
doing this frequently) . 

* Start up your other debugger. 

* You may now pop up the Soft-ICE window and 
turn the Soft-ICE break mode off if desired. 

11.2 User-Qualified Break Points 



Occasionally you may have the need for a very specific set of break point 
conditions. If the special conditions require qualifying register values 
or memory values, you can write a break point qualification routine. 
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C Soft-ICE contains a very general mechanism for calling user-written break 
point qualification routines: the ACTION command. When you use the ACTION 
command, Soft-ICE can route all break points through special interrupt 

[vector. However, before break points can be routed, the qualification 
routine must be placed in memory, and the interrupt vector must be 
pointing to the qualification routine. 

IaII registers are identical to the values when the Soft-ICE break point 
occurred. It is the responsibility of the qualification routine to save 

Cand restore the registers. If your qualification routine detects a match 
of break point conditions, it can do a variety of activities. Some 
examples of useful activities that a routine can do when a match is found 
are: 
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* store information for later 

* send the information directly to a printer or serial 

terminal 

* issue an INT 3 instruction to bring up Soft-ICE 

The command 13 HERE must be turned on in order 

for the INT 3 to bring up Soft-ICE (see section 5.4) 



*jlf conditions do not match, the qualification routine in should execute an 
I RET instruction. To summarize: 
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1. Create a break point qualification routine in your 

code space, or anywhere in free memory. The 
routine must preserve registers. After comparing 
the desired conditions, the routine can execute 
either an INT 3 to bring up Soft-ICE, or an IRET 
to continue. 

2 . Point an unused interrupt vector to your 

qualification routine. This can be done either 
within your code or from Soft-ICE. 



D 
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3. In Soft-ICE, set ACTION to the interrupt- number 

that was used to point to your qualification routine 

4. In Soft-ICE, set 13 HERE on. This is necessary to 

bring up Soft-ICE after the conditions have been 
met. 

5. Set the Soft-ICE general break point conditions. 

When any of these break point conditions are met, 
your qualification routine will be called. 

11.2.1 Example of a User-Qualified Break Point 



■ 



This section contains an example of a user-qualified break point that 
pompares for the conditions of U = 3 , BX - 4 and CX = 5 when a break point 
goes off. 



—First, we create the qualification routine. For the purposes of this 
example, we will assemble the command directly into memory with the Soft- 
ICE interactive assembler. For this example we will arbitrarily assemble 
the routine at location 9000: OH. The following statements are entered into 

|~jSoft-ICE: 

A 9000:0 
9000:0 CMP AX, 3 
9000:3 JNE 10 
9000:5 CMP BX,4 
9000:7 JNE 10 
9000: A CMP CX,5 
9000 :D JNE 10 
9000:F INT3 
9000:10 IRET 



D 
D 



D 



Now that the routine is in memory, you must point an interrupt vector to 

□the routine. For this example, we arbitrarily pick INT 99H. To place 
9000: OH in the INT 99H vector enter: 
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ED 0:99*4 9000:0 
214 



Set the ACTION command so that Soft-ICE will call your break point 
qualification routine on every break point. 



ACTION 99 



Set 13 HERE on so the qualification routine can activate Soft-ICE when the 
conditions occur. 
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13 HERE ON 



DNow you need to set the break points. For this example, we are just 
interested when the registers are: U = 3, BX = 4, CX - 5 in a specific 
program, and we do not want any further qualification. To do this, use a 
range break point on memory read: 
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BPR segment: starting-offset segment: ending-offset 



This will cause your break point qualification routine to be called after 
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every instruction is executed in the specified memory range. When the 
register conditions do not match, then the IRET instruction is executed. 

DWhen the conditions finally match the specified qualifications, the INT 3 
is executed and Soft-ICE is popped up. 

"When Soft-ICE pops up, the instruction pointer will be pointing at the 
|JlNT3 in your qualification routine (9000: FH in our example). To get to the 
instruction after the one that caused the break point, you must change the 

C instruction pointer to point to the IRET instruction (F000: 10H in the 
example) and single step one time. This is accomplished with the following 
Soft-ICE commands 
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RIP IP + 1 
T 



C After your break conditions have gone off, remember to change the ACTION 
command back to ACTION HERE that subsequent break points do not go through 
your qualification routine. 
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11.3 The Window in Graphics Mode 





Orhe screen is switched to text mode when Soft-ICE is invoked. If the^ 
screen was in graphics mode or 40-column mode, the graphics display is not 

D visible while the window is up. For users who must see the graphics 
display while debugging, three features are provided. The first feature 
allows the Soft-ICE window to display on a second monitor (see the ALT SCR 
command, section 5.9) . The second feature allows you to restore the screen 

C while you are doing P or T instruction step commands (see the FLASH 
command, section 5.9) . The third feature allows you to restore the program 
screen temporarily (see the RS command, section 5.9). 

[Jlf Soft-ICE does not seem to be following your program into graphics mode, 
try turning WATCHV on (see section 5.9 for details). 



| 11.4 Expanded Memory Debugging Features 



A range break point or a break point on memory that is set in an EMM 
Jjmappable area will stay at that address no matter which EMM page is mapped 

When debugging EMM programs, the EMMMAP command may also be very useful. 
See section 5.6 for more information. 

CThe D, E, S, F, and C commands can be used to view or modify any allocated 
EMM handle page. The page does not have to be currently mapped in. The 
syntax of these commands is similar to that of the commands when being 
used for non-EMM pages, except for the following: 
* In the D, E, S, and F commands, the address 

portion of the command must be specified in the 
following way: 
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Hhandle# Ppage# offset 
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where handle is a number specifying which EMM 
handle to use, page is a number specifying which 
EMM page to use, and offset is a number from to 
4000H, specifying the offset from the beginning of 



D 
D 


D 
D 
D 
D 
D 
D 



the page. 
Example: 

DB HI P3 

This command will dump bytes from page 3 of 
handle 1, starting at offset 0. 

The C command must be specified in the following 
way: 

C Hhandle# Ppage# offsetl L length offset2 

where handle and page are the same as above, 
offsetl is a number from to 4000H, specifying the 
offset from the beginning of the page, where the 
first data block to be compared is located. 
offset2 is a number from to 4000H, specifying the 
offset from the beginning of the page, where the 
second data block to be compared is located. 
Example: 

C H2 P4 00 L10 1000 

This command will compare the first 10 bytes of 
memory located at offset of page 4 of handle 2 
with the first 10 bytes of memory located at offset 
1000 of page 4 of handle 2. 



Note: 

Subsequent uses of the D, E, S, F, and C commands will continue to use the 
handle and page last specified. To get back to conventional memory, use 

Done of the above 
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commands with a segment specified in the address field, for example: 
D 0:0 
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11.5 Extended Memory Debugging Features 



The D, E, S, F, and C commands can be used to view or modify extended 
memory. Extended memory reserved by Soft-ICE can not be displayed. The 
syntax of these commands is similar to that of the commands when being 
used for conventional memory: 
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f In the D, E, S, and F commands, the address 

portion of the command must be specified in the 

following way: 

M megabyte address 

where megabyte is a number specifying which 
megabyte to use, and address specifies the address 
in the specified megabyte. 
Example : 
DB M 2 0:0 

This command will dump bytes from start of the 
megabyte starting at linear address 200000H. 
The C command must be specified in the following 
way: 

C M megabyte addressl L length address2 
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where megabyte and address 1 are the same as above. 
address2 specifies the address in the specified 
megabyte, where the second data block to be 
compared is located. 
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Example : 

C M 3 1000:2000 L10 3000:4000 

This command will compare the first 10 bytes of 
memory located at 1000:2000 with the first 10 bytes 
of memory located at 3000:4000. 



Note: 

Subsequent uses of the D, E, S, F, and C commands will continue to use the 
last megabyte specified. To get back to megabyte (conventional memory) , 
use one of the above commands with specified as the megabyte, for 
jjaxample : 
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CHAPTER 12 



D 

D 



Special Debugging Problems 

12 . 1 Loadable Device Drivers 

12.2 Boot Loaders 

12.3 Interrupt Routines 

12 . 4 Non-DOS Operating Systems 
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Soft-ICE can be a powerful tool in stand-alone mode. This chapter 
describes techniques for debugging system-level components using Soft-ICE 

Gin stand-alone mode. When using Soft-ICE as a stand-alone debugger, the 
ACTION must be set to HERE. 



12.1 Loadable Device Drivers 



1 



Debugging DOS loadable device drivers requires a debugger that does not 
make DOS calls. Soft-ICE can be used in stand-alone mode if your debugger 
uses DOS. 
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There are two methods for debugging loadable device drivers: 
1. Use the MAP command to find the location of your 
loadable driver. Display the device driver header 
to find the strategy or interrupt entry point. 
Setting a break point at the entry to strategy or 
interrupt will give you control within the device 
driver. Single step, or set break points further on, 
to continue debugging. 

Debugging the device driver initialization code 
requires resetting the system with the BOOT 
command. Use the technique stated above to set a 
break point within the driver code. The BOOT 
command will retain Soft-ICE and break points. 
■12 . The second method requires placing special code in 
your driver. Do this with the 13 HERE ON 
command (see section 5.4) . Place an INT 3 opcode 
(CCH) in your device driver at the point where 
control is desired. When the INT 3 executes, 
control comes to Soft-ICE. You can then use an 
RIP command to set the instruction pointer to get 
around the INT 3 . 



If you wish to debug your initialization sequence, make sure that Soft-ICE 
is loaded in CONFIG.SYS prior to the driver you are trying to debug. Place 
the 13 HERE ON command 
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in the INIT string in Soft-ICE. DAT. With this method you do not have to 
use the BOOT command. 



n If you are debugging your device driver symbolically or with source you 
must load the symbol file and the source files separately from the device 
driver. The symbol file and source files are loaded with the Soft-ICE 
program loader LDR.EXE. When LDR.EXE is used to load only the symbols and 

jjsource you must use it in the form: 

LDR file-name. SYM 



The extension of the symbol file must be specified. See section 7.4 for 
jnore details about LDR.EXE. 



After loading the symbol file and source files with LDR.EXE you must enter 
Soft-ICE and relocate the symbols relative to the start of your device 
pdriver. Symbols are relocated with the Soft-ICE SYMLOC command. The syntax 
of the SYMLOC command is: 



SYMLOC segment 
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The segment value is obtained from the MAP command. See the description of 
the SYMLOC command for more details. 



12.2 Boot Loaders 



[-Debugging boot loaders or self-booting programs requires using Soft-ICE as 
[W stand-alone debugger. You must first boot into DOS and load Soft-ICE. 
The easiest method of debugging boot loaders is to set a break point at a 
known address within the boot loader, and then use the BOOT command to 
reset the system. Soft-ICE is retained throughout the boot process with 
the break points still set. If a known address is difficult to find an 
execution break point can be set at 7C0:0H before the 
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nBOOT command. This is the address where the ROM BIOS loads the boot sector 
into memory. 



Another method requires turning 13HERE mode on (see section 5.4). Place an 
INT 3 opcode (CCH) in your program at the point where control is desired. 
When the INT 3 executes, control comes to Soft-ICE, 

You may also use both symbols and source debugging while debugging a boot 

C loader. See the SYMLOC command for more information on how to relocate 
your symbols and source to the segment where your boot loader has been 
loaded 
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12.3 Interrupt Routines 



Soft-ICE allows break points and single stepping within hardware interrupt 

C service routines (timer, keyboard, etc.). 
Single stepping and setting break points in interrupt service routines is 
allowed with Soft-ICE. You can even single step through the keyboard 
interrupt routine while Soft-ICE is using the keyboard for input. 
In most cases, Soft-ICE must be used as a stand-alone debugger when 
debugging interrupt service routines. To set a break point on the address 
of the interrupt service routine, use one of the following methods: 

1. Use the display double command: 
DD interrupt-number * 4 L 1 

The address displayed is the address of the first 
instruction of the interrupt service routine. Set a 
execution break point on this address. 

2 . Use the command : 
BPINT interrupt-number 
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12.4 Non-DOS Operating Systems 



Non-DOS real address mode operating systems can be debugged with Soft-ICE. 
If the operating system is not very DOS compatible you may have to load 



Soft-ICE under DOS, and then use the BOOT command to start the non-DOS 
operating system. Follow the instructions for debugging boot sequences and 
self-booting programs explained in section 12.2. 

The MAP and WARN commands may not function properly under a non-DOS 

C operating system, but break points and the other debugging commands will 
work correctly. 

DIf debugging with symbols or source you must load symbol files and source 
files while still under DOS or in the DOS compatible mode of your 
operating system. 
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Ll Theory Of Operation 

13 . 1 Activating Other Debuggers 
|j 13.2 Virtual Machine Basics 
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Hl3.1 Activating Other Debuggers 

Soft-ICE works with most other debuggers by taking advantage of the 8 08 6 
family break point interrupt (INT 3) . Most debuggers use the single byte 
L'lNT 3 (CCH) instruction to produce break points. The target instruction is 
replaced by an INT 3. When the target address is executed, control is 
given to the debugger's INT 3 handler. The debugger then replaces the 
(CCH) with the first byte of the original instruction. 
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When Soft-ICE break points occur, one of several events can happen, 
Paepending on the ACTION command. Typically, when using Soft-ICE with 
Lanother debugger, ACTION is set to INT3 . When break point conditions 
match, Soft-ICE passes control to the host debugger by simulating an INT 
3 . 
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Some debuggers may not work properly by simulating INT 3's. For these 

C debuggers, two other ACTION options are provided. They are INT1 and NMI. 
IX 1 is the 8086 family single-step interrupt. Most debuggers will handle 
an unsolicited INT 1 as a break point. NMI is supported by many debuggers 
as a means of breaking out of a hung condition. These debuggers were 
designed for hardware break-out switches that produced non-maskable 
interrupts. When ACTION is set for NMI, Soft-ICE simulates the non- 
maskable interrupt (Interrupt 2) . CODEVIEW works best with ACTION set to 
NMI. 



13.2 Virtual Machine Basics 



CThe magic of Soft-ICE is made possible by the virtual machine capability 
of the 80386 processor. Soft-ICE runs in the 80386 protected mode and 
manages the DOS environment. The 803 86 protection circuitry gives Soft-ICE 
("complete control of the DOS environment while protecting it from a wayward 
program . 
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How are Soft-ICE break points generated? 

D Soft-ICE uses three different 80386 features to produce break points: 
* Break points on memory location use the 80386 
break registers 

0* Break points on memory ranges use the 80386 
paging mechanism 
* Break points on I/O instructions use the I/O 
privilege level and I/O bit mask 
How is the BREAK command implemented? 



OThe BREAK command allows use of the keyboard to bring up Soft-ICE, even 
when interrupts are disabled and the system is hung. Soft-ICE virtualizes 
the interrupt mechanism so that interrupts are never disabled to Soft-ICE, 
even when they are disabled to the DOS program running in the virtual 



machine. 



When in break mode, the following instructions are virtualized to make 
sure the interrupt flag is never cleared: 



PUSHF 
POPF 
STI 
CLI 
INT n 
I RET 
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Soft-ICE runs DOS in an 8086 virtual machine. This capability is a ma 3 

C feature of the 8 0386 microprocessor. When running real address mode 
software (DOS, etc.) in a virtual machine some 8086 features must be 
emulated by a program that controls the virtual machine. In our case, 



Special considerations with virtual 8086 mode 
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C Soft-ICE controls the virtual machine. The following peculiarities are 
handled by Soft-ICE: 
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* -ROM BIOS interrupt 15H functions 87H, 88H, 

and 89H 

* The undocumented loadall instruction 

* Address line 20H control 

* 80286 and 80386 protected instructions 

* 80386 bugs 

ROM BIOS interrupt 15H functions 87H, 88H, and 
89H 

BIOS function 87H allows a program to access memory 
above one megabyte in the IBM AT or Personal Series 
11 architectures through a block move mechanism. 
Function 88H returns the extended memory size. 
These functions are used by the VDISK device driver. 
Soft-ICE emulates these BIOS calls for VDISK 
compatibility. Function 89H is normally used to put 
you into protected mode, but Soft-ICE can not allow 
this to happen. Instead it returns with the carry flag set 

The undocumented loadall instruction 

The 80286 contains an undocumented instruction 

called loadall. This instruction was originally placed on 

the chip for diagnostic purposes and is not generally 

used by software. However, it is used by some versions 

of Microsoft's RAMDRIVE which is sold with 

Microsoft Windows and MSDOS 3.2. Soft-ICE 

emulates loadall to the extent of getting RAMDRIVE 

to work, however it is impossible to do a complete 

emulation of this instruction. 
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Address line 2 OH control 



U 
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The IBM AT introduced a special feature that allowed some old programs 
that were originally written for CP/M to function on the 80286 processor. 
This feature allowed memory accesses that wrapped from the one megabyte 
region to the zero region on the 8086 to work on the 80286. Some programs 
disable this 'wrap compatibility' to access memory just above one megabyte 
[in real address mode. Soft-ICE emulates this ability. This is supported on 
all 80386 AT machines through the keyboard controller, and through I/O 
port 92H on the PS/2. 



80286 and 80386 protected instructions 

Some AT specific programs have used 80286 protected instructions. With the 
emergence of the 80386, some 80386 programs use 80386 protected 
instructions. These programs will not work with Soft-ICE. 



Soft-ICE supports the standard real-address mode extensions that Intel had 
'included with the 80186 & 80286 processors (PUSHALL, POPALL, etc.), but 
not protected mode instructions such as LGDT, LMSW, etc. 



80386 Bugs 

C There are several 80386 bugs up through the C stepping of the chip. Most 
pf these bugs only apply to protected mode software (such as Soft-ICE) . 
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APPENDIX A 



FUNCTIONAL COMMAND LIST 

Command Description Page 

[^Setting break points : 

BPM Set break point on memory access or 

□execution 54 

BPR Set break point on memory range 57 

BPIO Set break point on I/O port access 59 

BP I NT Set break point on interrupt 61 

□BPX Set/clear break point on execution 63 

CSIP Set CS:IP range qualifier 64 

BPAND Wait for multiple break points to occur 65 

[^Manipulating break points : 

BD Disable break points 68 

OBE Enable break points 69 

BL List break points 70 

BPE Edit break point 71 

BPT Use break point as a template 72 

BC Clear break points 73 

Display and edit commands: 

OU Unassemble instructions 77 

R Display or change register 79 

MAP Display system memory map 81 

D Display memory 83 

OE Edit memory 84 
INT? Display last interrupt number 86 

? or H Display help information 87 

|J VER Display Soft-ICE version number 88 

I/O port commands: 

□I Input from I/O port 90 

O Output to I/O port 91 
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] Command Description Page 
Transfer control commands: 

OX Exit from Soft-ICE window 93 

G Go to address 94 

T Trace one instruction 95 

□P Program step 96 

HERE Go to current cursor line 97 

GENINT Force an interrupt 98 

EXIT Force exit of current DOS program 99 

□BOOT System boot (retain Soft-ICE) 101 

HBOOT Hard system boot (total reset) 102 

□Debug mode commands: 

ACTION Set action after break point is reached 104 

W Set DOS/ROM BIOS re-entrancy 106 

warning mode 

□BREAK Break out any time 107 

13 HERE Direct Interrupt 3's to Soft-ICE 108 



[Utility commands 



A Assemble code 110 

S Search for data 112 

F Fill memory with data 113 

M Move data ' 114 

C Compare two data blocks 115 

Specialized Debugging Commands: 

SHOW Display instructions from history buffer 117 

□TRACE Enter trace simulation mode 119 

XT Single step in trace simulation mode 121 

XP Program step in trace simulation mode 12 2 

XG Go to address in trace simulation mode 12 3 

OXRSET Resets back trace history buffer 124 

VECS Save/restore/ compare interrupt vectors 12 5 

SNAP Take snap shot of memory block 127 

EMMMAP Display EMM allocation map 129 
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P Command Description Page 

Windowing Commands: 

OWR Toggle register window 131 

WC Toggle/set size of code window 132 

WD Toggle/set size of data window 133 

nEC Enter/exit code window 134 

Locate current instruction 13 6 

Debugger Customization Commands: 

□PAUSE Pause after each screen 138 

ALTKEY Set alternate key sequence to 139 

invoke Soft-ICE 

OFKEY Show and edit function keys 141 

BASE Set/display current radix 144 

CTPP Toggle log session to printer 145 

□Print-Screen Print contents of screen 14 6 

PRN Set printer output port 147 

Screen Control Commands : 

□FLASH Restore screen during P and T 149 

FLICK Screen flicker reduction 150 

WATCHV Set watch video mode 152 

DRS Restore program screen 153 

CLS Clear window 154 

ALT SCR Change to alternate screen 155 

DWIN Change size of Soft-ICE window 156 
Symbol and Source Line Commands: 

SYM Display/set symbol 159 

OSYMLOC Relocate symbol base 161 

SRC Toggle between source, mixed 162 
and code 

nFILE Change/display current source file 163 

SS Search current source file for string 164 
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ALPHABETIC 
Command 



COMMAND LIST 
Description 
Locate current instruction 

? or H Display help information 

A Assemble code 

ACTION Set action after break point is reached 

ALTKEY Set alternate key sequence to 

invoke Soft-ICE 

ALTSCR Change to alternate screen 

BASE Set/display current radix 

BC Clear break points 

BD Disable break points 

BE Enable break points 

BL List break points 

BOOT System boot (retain Soft-ICE) 

BPAND Wait for multiple break points to occur 

BPE Edit break point 

BP I NT Set break point on interrupt 

BPIO Set break point on I/O port access 

BPM Set break point on memory access or 

execution 

BPR Set break point on memory range 

BPT Use break point as a template 

BPX Set/clear break point on execution 

BREAK Break out any time 

C Compare two data blocks 

CLS Clear window 

CSIP Set CS:IP range qualifier 

CTRL-P Toggle log session to printer 

D Display memory 

E Edit memory 

EC Enter/exit code window 

EMMMAP Display EMM allocation map 

EXIT Force exit of current DOS program 

F Fill memory with data 

FILE Change/display current source file 
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[-Command 
I FKEY 
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FLASH 
FLICK 
G 

GENINT 
HBOOT 
HERE 
I 

13HERE 

INT? 

M 

MAP 



P 

PAUSE 
Print- 
PRN 



Description 
Show and edit function keys 
Restore screen during P and T 
Screen flicker reduction 
Go to address 
Force an interrupt 
Hard system boot (total reset) 
Go to current cursor line 
Input from I/O port 
Direct Interrupt 3's to Soft-ICE 
Display last interrupt number 
Move data 

Display system memory map 
Output to I/O port 
Program step 
Pause after each screen 
Screen Print contents of screen 
Set printer output port 
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110 
104 

139 
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144 

73 

68 

69 

70 

101 

65 

71 

61 

59 

54 

57 

72 

63 

107 

115 

154 

64 

145 

83 

84 

134 

129 

99 

113 
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108 
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114 
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138 
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R 

RS 

S 

SHOW 
SNAP 
SRC 

SS 
SYM 

SYMLOC 
T 

TRACE 
U 

VECS 

VER 

WARN 

WATCHV 
WC 
WD 
WIN 
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Display or change register 
Restore program screen 
Search for data 

Display instructions from history buffer 
Take snap shot of memory block 
Toggle between source, mixed 
and code 

Search current source file for string 
Display/set symbol 
Relocate symbol base 
Trace one instruction 
Enter trace simulation mode 
Unassemble instructions 
Save/restore/compare interrupt vectors 
Display Soft-ICE version number 
Set DOS/ROM BIOS re-entrancy 

warning mode 
Set watch video mode 
Toggle/set size of code window 
Toggle/set size of data window 
Change size of Soft-ICE window 



WR Toggle register window 



Command 
J X 
XG 
XP 

XRSET 
XT 
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Description 
Exit from Soft-ICE window 
Go to address in trace simulation mode 
Program step in trace simulation mode 
Reset back trace history buffer 
Single step in trace simulation mode 
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KEYSTROKE FUNCTION LIST 

Keystroke Description 
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Moving the Soft-ICE window: 

CTRL Move window one row up 

CTRL Move window one row down 

CTRL Move window one row right 

CTRL Move window one row left 



[^Resizing the Soft-ICE window: 



: 
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ALT 
CTRL 



Expand the window 
Shrink the window 



Editing the Command Line: 

Move the cursor to the right 
Move the cursor to the left 
INS Toggle insert mode 

DEL Delete current character 

HOME Move cursor to the start of the line 



D 
D 
D 
D 



END Move cursor to the end of the line 

Display the previous command 
Display the next command 
SHIFT Scroll one line up in display 

SHIFT Scroll one line down in display 

PAGE UP Scroll one page up in display 
PAGE DN Scroll one page down in display 
BKSP Delete previous character 

ESC Cancel current command 
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APPENDIX D 

Error Messages and Descriptions 
This appendix lists and explains the error messages that can 
be generated by Soft-ICE. 

A General Protection Violation Has 
Occurred. This is typically caused 
by a protected mode instruction. 
CS:IP = XXXX:XXXX 
Type 'C to Continue 
Type 'R' to Return to Soft-ICE. 

This message can occur either when an 80386 
protected mode instruction is encountered or if there is 
a segment wrap-around condition. You can often 
determine the reason for this message by 
un-assembling the instruction at the specified address. 
If the first byte of the instruction is an OFH, then it is 
probably a protected mode instruction. If the 
instruction is accessing a word at offset OFFFFH in a 
segment then it is a segment wrap problem. If you type 
C to continue, then control is given to the interrupt 
handler in the DOS virtual machine. 

This message often occurs when a program jumps to an 
address that does not contain valid code or when valid 
code has been overwritten. 

Attempt To Divide By 

This message is displayed when Soft-ICE evaluates an 
expression and the divisor in a divide operation is zero. 
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BPM Break Point Limit Exceeded 



Soft-ICE allows a maximum of 4 memory break points. 
This message is displayed ifyou attempt to exceed the 
maximum limit. 

Break Point Table Full 
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Soft-ICE allows a maximum of 16 break points. This 
message is displayed if you attempt to exceed the 
maximum limit. 

Count Too Large 

The Soft-ICE break point commands allow an optional 
count field. This field can contain a maximum value of 
FFH. This error message is displayed if the count 
value specified is greater than FFH. 

DOS Memory Structures Corrupted 

This message is displayed if Soft-ICE detects a problem 
with the DOS memory block chain when using the 
MAP command. This message can also occur if you use 
the MAP command with a non-DOS operating system. 

Duplicate Break Point 

When a break point is entered, Soft-ICE compares the 
break point conditions with those of break points that 
had been set previously. If the conditions match, this 
message is displayed. 
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Interrupt Break Point Limit Exceeded 

Soft-ICE allows a maximum of 10 interrupt break 
points. This message is displayed if you attempt to 
exceed the maximum limit. 

Invalid Opcode Has Occurred 

CS:;iP =XXXX:XXXX 

Type 'C to Continue 

Type 'R' to Return to Soft-ICE. 

When the 80386 encounters an instruction that is 
illegal, it generates an interrupt 6. Soft-ICE displays 
this message and gives you the opportunity to continue 
or to return to Soft-ICE. If you type C to continue, 
then control is given to the interrupt 6 handler in the 
DOS virtual machine. 

This message often occurs when a program jumps to an 
address that does not contain valid code or when valid 
code has been overwritten. 

I/O Break Point Limit Exceeded 

Soft-ICE allows a maximum of 10 I/O break points. 
This message is displayed if you attempt to exceed the 
maximum limit. 

No Alternate Screen 

This message is displayed if the ALT SCR command is 
used and Soft-ICE detects only one video adapter. 



Parameter is Wrong Size 



Certain fields require a specific data type size (byte, 
word or double word) . This message is displayed if the 

245 

data type size is exceeded. For example, if you use the 
command 'BPMB 2000:2000 EQ 12 34' you are asking 
Soft-ICE to look for a byte access at location 2000:2000 
with a value of 1234H. Since 1234H is larger than a 
byte, the command causes this error message to occur. 

Parameters Required 

Most Soft-ICE commands require one or more 
parameters. If a command is entered without the 
required number of parameters, this message is 
displayed. 

Range Break Point Limit Exceeded 

Soft-ICE allows a maximum of 10 memory range break 
points. This message is displayed if you attempt to 
exceed the maximum limit. 

Second Parameter Must Be Greater than First 

When specifying a memory range, the first number 
entered must be the lower limit of the range, otherwise 
this message is displayed. 

Segment: Of f set Can Not Wrap 

Most Soft-ICE commands do not allow a memory 
■pointer (segment: of f set) to wrap from high memory to 
low. For example, the memory pointer FFFF: FFFF 
wraps and is illegal. This message is displayed if you 
attempt to wrap from high memory to low. 
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Soft-ICE cannot be loaded. 

Needs to load at top of memory. 

Load before any TSR's or control programs. 

Soft-ICE needs to load itself at the highest memory 
location possible. This memory is then 'mapped out', 
making it invisible to DOS programs, so they can't 
crash Soft-ICE. This message is displayed if Soft-ICE 
detects that another program has already been loaded 
at the top of memory. 

Soft-ICE cannot run with other 803 86 control programs 

The 80386 only allows ore protected mode program 

a time, so Soft-ICE can not coexist with other control 

programs. When debugging a program that use EMS 

and EEMS, you could get this error message when you 

try to load Soft-ICE, because some 80386 systems come 

with a control program that uses the 80386 paging 
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system to give you EMS and EEMS with a board that 
only has extended memory. You can, however, use a 
true expanded memory board to debug programs that 
use EMS and EEMS. 

Soft-ICE has already been loaded 



This message occurs if you attempt to load Soft-ICE 

D twice. 
Soft-ICE has not been loaded 
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This message occurs if you attempt to unload Soft-ICE 
when it has not yet been loaded. 
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Soft-ICE loads at the top of extended memory. This may conflict with other 

C programs that use extended memory. If you are sure it will not conflict, 
jthen answer ' V , otherwise answer 'N' and refer to the chapter on loading 
Soft-ICE with extended memory. 
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This message occurs if you attempt to load Soft-ICE 
into extended memory, and S-ICE.SYS was not loaded 
in your CONFIG.SYS file. This warning is given to 
insure that you do not unintentionally wipe out a 
virtual disk or another program that may be loaded in 
extended memory. For more information, refer to 
section 2.2, "Loading Soft-ICE" and chapter 6, 
"Initialization Options". 

Soft-ICE will only run on 80386 based machines 

Soft-ICE requires Intel's 80386 microprocessor. 

Syntax Error 

This message is displayed if the information that was 
entered did not fit within the structure of any Soft-ICE 
command . 

The P & G Commands Function In RAM Only 

Soft-ICE uses two methods to implement the P and G 
commands. The first method uses the 80386 break 
point registers. However, if you have already set 4 
BPM-style break points, Soft-ICE uses the INT 3 
method, which will only work in RAM. If you attempt 
to use the P or G commands in ROM at this point, 
Soft-ICE detects this condition and displays this error 
message. 
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Valid Verbs are R, W, RW, X 



This message is displayed if an invalid verb is specified 

in a BPM command. When using the BPM command, 

the valid choices for verbs are R(read), w(write) , 

RW (read/write) , and X (execute) . 
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APPENDIX E 

jjFROUBLE shooting guide 



This appendix gives solutions to some possible problems that you could 
encounter when using Soft-ICE. If you do not find the problem here, check 
the README. SI file on your distribution diskette for any troubleshooting 
hints that may not have made it into this manual. 
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Time does not show the correct time at the end of the day. 

Soft-ICE does not let any interrupts go through to the 
system when the Soft-ICE window is up. This does not 
affect the real time clock at all, so the next time you 
reboot, the time will be displayed correctly again. You 
can also correct the time by running the program 
UPTIME. This gets the time from the real time clock 
and calls DOS to set the time. 



C: 
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When debugging a program that uses EMS and EEMS, you get this error 
message when you try to load Soft-ICE "Soft-ICE cannot run with other 
80386 control programs". 



Some 386 systems come with a control program that 
uses the 80386 paging system to give you EMS and 
EEMS with a board that only has extended memory. 
The 3 86 only allows one control program at a time, so 
Soft-ICE can not coexist with these control programs. 
You can, however, use a true expanded memory board 
to debug programs that use EMS and EEMS. 

Soft-ICE does not cause your software debugger to break. 

Some software debuggers will break only when used 
with one type of debugging interrupt. Refer to the 
ACTION command in section 5.4. This lists three 
different types of standard action that can be taken 
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when a break point happens. Try all three. Different 
ones work better for different debuggers. 
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Soft-ICE does not come up when your monitor is in graphics mode, or it 
does not restore your graphics screen correctly. 



Soft-ICE does not use the ROM BIOS for its output, 
it must go directly to the hardware. Soft-ICE was 
designed to work with the following types of 
controllers, or ones that are 100% compatible: 

CGA 

MDA 



Hercules 
EGA 

I VGA 
If your controller is not one of these, or not 100% 
compatible, you can use a second controller and 

] monitor, and use the ALT SCR command described in 
section 5.9. 

The key sequence used to bring up Soft-ICE conflicts with an existing 



You can set a different key sequence to bring up 
Soft-ICE by using the ALTKEY command. If this 
doesn't work, add the SHIFT key to the current key 
sequence and use this new key sequence to bring up 
the existing program. Soft-ICE will not respond to the 
new key sequence, and will allow it to go through to the 
existing program. Refer to the ALTKEY 
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running. 
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command in 
section 5.8. 

When your program crashes, Soft-ICE will not come up. 
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Refer to the BREAK command in section 5.4. This 
command allows you to pop up the SoFt-ICE window 
when the system is hung with interrupts disabled 

252 



After your break point triggers your debugger, your debugger does not 
^respond . 

There are two possible reasons why this problem could 
occur: 

1) Your debugger has caused DOS or ROM BIOS to 
be re-entered. DOS and ROM BIOS are not fully 
re-entrant, so your debugger may not work 
correctly. Use the WARN command to turn 
re-entrancy warning mode on. The next time DOS 
or ROM BIOS is about to be re-entered, a warning 
message will be displayed, and you will be able 
choose to return to Soft-ICE to avoid the problem 
Refer to the WARN command in section 5.4. 

2) A break occurred in the middle of an interrupt 
routine. Some debuggers can not handle this 
occurrence. Use ACTION set to HERE, because 
Soft-ICE will allow you to break in the middle of 
an interrupt routine. Refer to the ACTION 
command in section 5.4. 



D 
D 
D 
D 
D 



CYou are using a CGA monitor and you get lots of flickering when Soft-ICE 
comes up. 
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Certain types of video cards will flicker if characters 
are output without waiting for horizontal or vertical 
retrace. To reduce the flickering, turn FLICK mode 
ON. Refer to the FLICK command in section 5.9. 



When you use the BOOT command, the system starts to reboot but then hangs 

Soft-ICE uses the interrupt 19 method of soft-booting. 
There are two possible times when this method could 
fail: 
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1) On a freshly booted system this method will work 
fine. But if the system has been corrupted by an 
errant program, there is a chance that this method 
will not work. 
2) Some programs that use extended or expanded 

memory, such as EMS drivers or disk caches, are 
not able to handle an interrupt 19 style boot. 
When debugging device drivers and boot loaders 
that have this problem, you should use the 
following method. Boot the system without the 
drivers that cause the problem; load Soft-ICE; set 
up the drivers to load on the next boot; and then 
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use the BOOT command. Refer to the BOOT 
command in section 5.3. 

-You just used the SYSREQ key sequence to bring up Soft-ICE, and your 
system appears to be hung, or it begins to dump the screen to your 
Qpr inter . 

On some keyboards, you must press the ALT key and 
the PrtSc key simultaneously to generate a system 
request. If you accidentally press only the PrtSc key, 
the system will attempt to print your screen. If no 
printer is attached, your system will appear to be hung. 
To avoid this problem, be careful to press both keys 
simultaneously, or use the ALTKEY command to 
change to a different key sequence. Refer to the 
ALTKEY command in section 5.8. 

You were unassembling instructions, or editing or displaying memory when 
your debugger crashed. 



D 

D 



D 
D 
D 

D 
D 

C; 
D 
D 



You accessed an address that triggered a Soft-ICE 
break point, and ACTION was not set to HERE. 
When Soft-ICE brings you to the point where you want 
to look around in memory with your debugger, you 
should disable the Soft-ICE break points. If you don't 
you could set off a break point unintentionally. This 

254 

would cause your debugger to trigger itself, which can 
be a fatal problem with debuggers that cannot be 
re-entrant. 

After you exited from your debugger, the system crashed. 

This problem of course could have many causes, but 
one possible cause is that you may have forgotten to 
disable the Soft-ICE break points, and ACTION is still 
set to trigger your debugger. When the break point 
occurs, ACTION will attempt to trigger your debugger, 
but your debugger is no longer loaded. 

jYou set a break point to trap on Interrupt 15H, function 87H, 88H, or 89H, 
and the break point did not occur. 



Soft-ICE processes these functions internally in 
protected mode, so you cannot set break points on 
these functions. 

Your program does not accept keystrokes, but the keyboard is still active. 



OA shift state key may be logically stuck down. Try 
pressing and releasing each shift, control and alt key. 

Soft-ICE does not restore your graphics display properly. 

Soft-ICE has an enhanced video virtualization mode 
that can virtualize many special graphics modes. Turn 
this mode on by entering WATCHV ON. See the 
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description of the WATCHV command for more 
details. For non-compatible video controllers and 

□certain obscure modes you may have to use an 
alternate monitor. See the ALT SCR command. 
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The machine locks up while you are in Soft-ICE or moving the Soft-ICE 
■ window. 

Soft-ICE has timing problems with some keyboards. 
Use the NOLEDS statement in S-ICE.DAT. This 

□prevents Soft-ICE from sending LED commands to the 
keyboard . 
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Introduction 



This release memo is an addendum to the Soft-ICE 2.0 User's Guide. It 

C describes the differences between the Soft-ICE 2.0 User's Guide and the 
Soft-ICE 2.5 release. When this memo is referring to enhancements or 
changes made to features that existed in the Soft-ICE 2.0 Us 
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the memo headings will include, in parenthesis, the chapter number of the 
corresponding information in the Soft-ICE 2.0 User's Guide. Please read 
both the Soft-ICE 2.0 User's Guide and this release memo. 
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4 Soft-ICE Addendum 

Product Description ( 1, 1 ) 

There have been many features added to the Soft-ICE 2.5 release. The 
principal features are that Soft-ICE: 
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* integrates with BOUNDS-CHECKER. 

* reads symbolic and source information directly 
from the .EXE header from Microsoft & 
Borland languages. 

* has overlay support for Microsoft's LINK and 

Pocket Soft's .RTLink/Plus. 

* can have two symbol tables loaded at the same 
time. 

* allows 386 32-bit instruction dis-assembly and 

3 2 -bit register dump. 

* is Microsoft C version 6 compatible. 

* provides numeric processor dis-assembly. 

* lets device drivers and T&SR programs load 

high 

* includes some additional commands: 

BOUNDS, TABS, STACK, SERIAL. 

* includes enhancements to some existing 

commands: R, FILE, SHOW, BPX, G. 

* has VCPI support. 

Soft-ICE Addendum 2.5 5 

* allows remote debugging 

* has 80486 support. 

* allows customizes Soft-ICE window colors. 
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The Diskettes (2, 1), 



A directory of a Soft-ICE 2.5 diskette will now show the following 



additional files 



\NEW\LH. 
\NEW\LD.SYS 
\NEW\ADDHI.EXE 
\NEW\CE.EXE 
\I0SIM.ASM 
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LH.EXE is a utility that loads high T&SRs. LD.SYS is a utility that loads 
r high DOS loadable device drivers. ADDHI.EXE is a utility that adds high 
memory to DOS memory chain. CE.EXE is the CONFIG.SYS editor. I0SIM.ASM is 
an example of a user qualified break point. It will take a BPIO break 
point and log all the values that were written to or read from that port. 
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Loading Soft-ICE (2.2) 
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Follow the installation instructions in the Soft-ICE 2.0 User's Guide to 
fbopy all the files from the root directory of the distribution diskette to 
your Soft-ICE directory on your hard disk. In addition, copy the files 
from the /WW directory on the distribution diskette to your Soft-ICE 

D directory on your hard drive; these files are new with the Soft-ICE 2.5 
release. 

Note 

If you were previously using Soft-ICE 

2.0 with the /EMM option on the S ICE command line in 

CONFIG.SYS, 

you need to run EMMSETUP. Since 
EMMSETUP writes configuration 

information directly into the S ICE. EXE file, this 
information was 

over-written when you loaded Soft ICE 2.5. 
8 Soft-ICE 2.5 Addendum 
Using Soft-ICE with BOUNDS -CHECKER (New feature) 
Introduction 



Q 
□ 
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[^BOUNDS-CHECKER gives you the protection of a protected mode operating 
system under MS-DOS. When your program is running, BOUNDS-CHECKER protects 

Cyour program's CODE and all memory outside your program. When an MS-DOS 
system call or BIOS call or interrupt occurs, BOUNDS-CHECKER prevents the 
system software from corrupting your program. So BOUNDS-CHECKER can not 
only detect problems caused by your program, it can also determine if a 
Qr&SR or other program is clobbering you. 

Each time you make a change to your program, run BOUNDS-CHECKER while 

C testing the new code. Your program runs at full speed, and if you 
accidentally access out-of-bounds memory, BOUNDS-CHECKER pops up 
displaying the offending source line. 

Using Soft-ICE in combination with BOUNDSCHECKER is very useful when the 
bug found by BOUNDS-CHECKER is not clearly self-explanatory. You may need 
to use Soft-ICE to look at data, to debug a little, or to rerun the 

Hprogram with Soft-ICE' s back trace capability to determine why the out-of- 

L'bounds access occurred. . 
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JjLoading BOUNDS-CHECKER to use with Soft-ICE 2.5 
To use BOUNDS-CHECKER with Soft-ICE 2.5, you must first 
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1. Install BOUNDS-CHECKER on your hard 
disk using the BOUNDS-CHECKER 
installation program (BCSETUP.EXE). 

2. Replace the DEVICE=d: \path\BC. SYS line 
in your CONFIG.SYS file with 
DEVICE=d: \path\S-ICE.EXE. 
Use the same parameters that were on the 
BC.SYS command line. In addition, you may 
want to use the /TRA nnnn parameter to 
create a back trace buffer larger than 10K. 
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You may also need to increase the size of your 
/SYM nnnn parameter to allow your source 
and your symbols to be loaded. 
Notes 

You do not need the /BC switch on 
the DEVI CE=d: /path /S-ICE.EXE 
line in CONFIG.SYS as the 
BOUNDS-CHECKER manual states. 
You must have Soft-ICE version 2.5 
or greater and BOUNDS-CHECKER 
version 1.1 or greater for them to 
coexist. 
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Run BOUNDS -CHECKER. When BOUNDSCHECKER pops up # if you want to enter Soft- 
ICE to do further debugging, select Options on the main menu, then select 
^Soft-ICE. To re-enter BOUNDS-CHECKER, simply exit Soft-ICE with the hot 
key sequence or the X command. 

If you don't have enough extended memory to run BOUNDS-CHECKER, you can 
save space by running BOUNDS-CHECKER with option /S in this form: 



10 Soft-ICE 2.5 Addend 

Running Soft-ICE 2.5 with BOUNDSCHECKER 



n 



BC /S program-name 



This stops source from loading up into extended memory for use by Soft- 
ICE. The disadvantage is that Soft-ICE will show line numbers, but will 
not show source code. 
Note 

Soft-ICE range break points and back 
trace ranges will be disabled while the 
BOUNDS-CHECKER is running. 
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The Soft-ICE BOUNDS Command 



The new command, BOUNDS, is used for turning BOUNDS-CHECKing on and off 

Ofrom within SoftlCE. This is useful if you want to stop to do some 
debugging from within a BOUNDS -CHECKER 
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session, then return to BOUNDS-CHECKing after you have debugged a portion 
of the program. 



The syntax of the BOUNDS command is: 
BOUNDS [ON | Off) 



BOUNDS OFF turns off BOUNDS-CHECKing, and BOUNDS-ON turns BOUNDS-CHECKing 

nback on. If no parameters are specified, then the current state is 
displayed. 
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Overlay Support (New feature of BPX and G commands) 
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The Soft-ICE BPX break point will follow overlays produced by the 
Microsoft linker or .RTLink/Plus. 



The BPX and G commands allow you to use break points in overlays. Other 
break point types do not follow overlays. To use BPX to set a break point 
in an overlay, you must type: 

BPX routine_name 

Other forms of BPX, such as using source line numbers or setting BPX using 
point-and-shoot, do not follow break points in overlays. 
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32 Bit Dis-assembly and Register Display (5.1 - R command) 



Psoft-ICE now displays 32 bit 80386 instructions properly. The Dis-assembly 
is always enabled. To enable 32 bit register display in the data window 
enter: 
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R 32 

jrhis toggles between 16 bit and 32 bit registers. 
STACK Command (New command) 
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Soft-ICE 2.5 now allows you to display the call stack. A call stack is a 
list of routines that were called to reach the current address. Using the 
call stack is especially useful when Soft-ICE pops up in a library 
routine. By using the call stack, you can quickly see the last routine in 
your program that had control before entering the library, even if the 
program is several levels deep into library calls. 

PThe most recently called entry in the stack is displayed first in the 
command window. 
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The format of the call stack is: 

procedure (of f set) [line-number] 



If line-number is a '?' then no line number information was available for 
this procedure. 



D 



14 Soft-ICE Addendum 



The STACK command can only be used if symbolic information is loaded. 
If the module of an entry in the call stack was not compiled with debug 
information, no symbolic label will be displayed. Only a hexadecimal 
offset will be shown. 

QSHOW Command (5.6) 

The SHOW command has been enhanced to allow you to dump large amounts of 

nback traced instructions to the printer, 
the new syntax for SHOW is: 
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SHOW [B | start] [L length] 
B - start at beginning of buffer 
start - number of instructions back to begin 
length - number of instructions to display 



D. 



1 



If SHOW is used with the length argument, you can use CTRL P to dump the 
pis-assembled source to the printer. If you don't specify B or start, it 
starts displaying at the current location. 



FILE Command (5.10) 
The FILE command has been enhanced. The new syntax for FILE is: 
FILE [file-name |*] 
Soft-ICE 2.5 Addendum 15 



D 



D 



FILE * displays all source files that have been loaded by LDR.EXE into 
'extended memory. 



rTo switch to a new file with the FILE command you no longer have to type 
[the full path name or file extension. For example, to switch to file 
C:\S0URCE\F00.C, pop up Soft-ICE and enter FILE F00. 
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Preparing For Symbolic or Source Debugging (7,2) 
Microsoft and Turbo Source/ Symbolic Improvements 



Soft-ICE 2.5 has made source and symbolic improvements for users of 
Microsoft or Turbo languages. 



Soft-ICE can now get the symbolic and source information directly from the 
f~|. EXE file if there is Microsoft CodeView compatible or Turbo Debug 
compatible debug information in the. EXE file. MSYM.EXE, the. MAP file, and 
the.SYM file are no longer needed if the debug records are present. 

GWith Microsoft, compile with /Zi and link with /CO. With Turbo, compile 
tfith /v and link with /v. 

CThe /CO switch makes the linker append symbolic information to the end of 
your . EXE file, although this will make your. EXE file grow in size, this 
will not affect the amount of conventional memory required by your 
program . 
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□ Note 
MSYM.EXE is useful when you are 
using a compiler that produces a 

□Microsoft Link compatible .MAP file, 
but does not place Microsoft 
compatible debug information in the 
.EXE file. 

Ql8 Soft-ICE Addendum 



□Loading Programs and Symbol Files (7,4 and new TABLE command), 
Multiple Symbol Tables 

Soft-ICE 2.5 can now handle two symbol tables. This is useful when 

L debugging a T&SR or DOS loadable device driver with an application, or 
debugging a shell with a child process. 

jjTo load a separate symbol table or a separate program with symbols use the 



Soft-ICE TABLE command. TABLE 1 uses symbol table number one, TABLE 2 uses 
symbol table number 2. 

n 

To use two symbol tables, do the following: 



D 
D 



1. Use LDR to load your first program and 

symbolic information, 

2. Pop up Soft-ICE. 

3 . Enter TabLE 2 . 

4. Exit Soft-ICE. 

5. Use LDR. EXE to load the second symbol 
table. 



Both sets of symbolic information are now loaded into extended memory and 
you are currently viewing the second set of symbolic information. Use the 
TABLE 1 and TABLE 2 commands to toggle between which set of symbolic 
information you are currently viewing. 



To view your first program's symbolic information, pop up Soft-ICE if it's 
not up already, and enter: 



D 

D 
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TABLE 1 



To view your second program's symbolic information, pop up Soft-ICE if 
it's not up already, and enter: 



D 



TABLE 2 



If you enter TABLE without any parameter, it will tell you which set of 
^symbolic information is currently being viewed. 

Note 

When you re-load table 1 by entering 
TABLE 1 then loading with LDR, 

table 2 is invalidated. 



D 



■ 



Tabs Control (New TABS comm 



D 
D 
D 
D 
D 



D 



and) 



Soft-ICE 2.5 allows you to control tab expansion size of source files. 
Previous versions of Soft-ICE assumed tabs of every 8. The syntax for the 
TABS command is: 



D 
C 



TABS [2 | 4 | 8] 



If no parameter is specified then the current tabs setting is displayed. 
Kyi interesting use of the TABS command is to see more than 78 characters 
of source on a single line. To do this enter TABS 2. 
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Remote Debugging (New feature and new SERIAL command) 





Soft-ICE is capable of displaying all of the information from the command 
window over a serial port. The hot key is still activated via the system 
keyboard but once Soft-ICE is popped up, both the system and the remote 
keyboard will be active. To activate remote debugging use the following 
Usequence: 

1) Set the BAUD rate with the DOS MODE 
command to the same baud rate as the remote 
terminal . 

2) Within Soft-ICE, set PRN to the correct serial 
port. 



Example: PRN COM1 




D 



D 
D 
D 



3) Within Soft-ICE, enter SERIAL ON. At this 

point, you may enter information on either 
keyboard, and the command window output 
will go to both screens. 
'4) You will probably want to get rid of your Code, 

Data and Register windows as these will not be 
displayed across to the remote terminal. 
5) If you do not want the Soft-ICE screen up on 

the host machine then turn ALTSCR ON from 
within Soft-ICE. 
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486 Support (New Feature) 



Soft-ICE 2.5 now has 80486 support. Previous versions did not, due to 
anomalies with the 80486 processor. Also 486 instructions will be 
disassembled correctly 



U 

D 

D 



22 Soft-ICE 2.5 Addendum 
Special Configuration Options (6.4.1) 
Soft-ICE color support 



Soft-ICE 2.5 now allows you to specify the screen colors for the Soft-ICE 
windows. 



D 







To set colors for the different windows in Soft-ICE you must use the 
COLORS directive in the S-ICE.DAT file. The syntax of the COLORS command 

C is: 

COLORS = n nnH,nnH,nnH,nnH,nnH,nnH, nnH,nnH,nnH,nnH,nnH,nnH 

there nn is a HEX number. There are four sets of three numbers. Each 
grouping of three affects the colors of a particular window. The ordering 
for the four Soft-ICE windows is: 







COLORS register-window, data-window, code-window, command-window 
Each grouping of three HEX numbers controls the normal attribute, 
[""highlight attribute and reverse attribute for the respective window. The 
L'actual number is the value that is placed in the attribute field in the 
video frame. The high order nibble is the background color and the low 
order nibble is foreground color. The colors are: 

- black 1 - blue 2 - green 
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D 



D 



D 



3 - cyan 4 - red 5 - magenta 6 - brown 7 - gray 
8-OF are intense versions of the above. 




D 



An example of the colors command is: 

COLORS = "47H,4EH,7EH, 07H,OFH,70H, 17H, 1FH, 71H, 3 OH, 3FH, 71H" 
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Expanded Memory Support (8) 



pThe expanded memory manager has been enhanced in Soft-ICE 2.5, and 
[futilities are now provided to load device drivers and T&SR programs into 
extended memory. (The expanded memory manager is enabled with the /EMM 
command when S-ICE.EXE is placed in your CONFIG.SYS.) 



D 



EMMSETUP.EXE Changes 



["Running EMMSETUP.EXE (the expanded memory manager setup program) now 
requires a command line parameter that specifies the name of the expanded 
memory manager file. The syntax for running EMMSETUP is: 



D 



EMMSETUP file-name 



The file-name parameter should be S-ICE.EXE. EMMSETUP can also be used 
With MagicCV release 3.0, in which case the parameter should be 
NUMEGA. SYS. This parameter is required because EMMSETUP writes the 
configuration information directly into the driver file. 

C EMMSETUP now has the option of enabling memory blocks for loading high of 
device drivers and T&SR programs. You must select this feature on 
EMMSETUP ' s initial screen. 



D 
D 
D 



The EMMSETUP configuration memory map now has more choices. You can choose 
F for page frame, and H 
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for high memory areas. To enable expanded memory you must have 4 and only 
4 contiguous F's above 64 OK. To load high device drivers or T&SRs you must 



place H's in UN-occupied memory blocks above 640K. 
Note 

If you want to load high device drivers 
& T&SR programs, but do not want 
EMM (expanded) memory, then make 

]sure there are no E's or F's in the 
memory map. 



[^Loading High Of Resident Programs (New feature) 

The LH.EXE utility allows loading certain resident programs into 
available memory blocks between 640K and I megabyte. Before using LH.EXE 
Lyou must reserve memory for loading high using EMMSETUP.EXE. This is done 
by placing an 'H' in each memory block above 640K that you wish to have as 

ra load high area. 
To load a resident program high enter: 



D 



LH program-name [program parameters] 



If there is a high memory block large enough to hold the program, the 
program will be loaded into it. 

Dlf no program-name follows LH on the command line, a memory map is 
displayed of the DOS loadable device 
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< 

D 



□ 



drivers and resident programs loaded high along with available memory. 
Note 

You can not load all resident 
programs with LH.EXE. You must 
experiment to see which programs can 
be loaded high. 



Loading High Of MS-DOS Loadable Device Drivers (New feature) 



The LD.SYS utility allows loading certain MS-DOS loadable device drivers 
into available memory blocks between 64 OK and I megabyte. Before using 

G LD.SYS you must reserve memory for loading high using EMMSETUP.EXE. This 
is done by placing an 'H' in each memory block above 64 OK that you wish to 
have as a load high area. 

[jTo load an MS-DOS loadable device driver high, you must place the 
following line in your CONFIG.SYS file: 

C DEVICE = \path\LD.SYS device-name [parameters] 
path - Path containing LD.SYS 
device-name - Name of DOS Loadable 

device driver including path 



D 



If there is a high memory block large enough to hold the device driver, 
the program will be loaded into it when you boot. 
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D| To display a memory map of DOS loadable device drivers and resident 
programs loaded high use the LH utility with no parameters from DOS. 
Note 

You can not load all DOS loadable 



D 



^is installed in CONFIG.SYS. 

Qsof 
D 

D 
D 
D 
D 
D 
D 
D 

D 
D 
D 
D 
D 
D 
D 
D 
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Back Door Commands (New feature) 



Sof t-ICE 2.5 contains commands for controlling SoftlCE from an MSDOS 

D program. A program can take advantage of powerful break points for special 
debugging jobs or hardware simulation projects. 



These calls all have the following calling sequence: 
MOV AH, 09 

MOV AL, SUB-FUNCTION 
MOV SI, 'FG' 
MOV DI, ' JM' 
INT 3 

The sub-functions are available: 
AL value Description 

10H Display information in the Soft-ICE 

window. 
11H Do a Soft-ICE command. 
12H Get break point information. 
13H Set Soft-ICE break point. 
14H Remove a Soft-ICE break point. 
The following paragraphs give more detailed information about these 
subf unctions. 



r 

D 
D 



D 
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AL = 10H — Display Information In the Soft-ICE window. 
This is useful for diagnostic writes - especially from within interrupt 
^routines and other areas that may have reentrancy concerns. 

Input: DS:DX - > Zstring of text characters to be 
displayed 



D 



D 



The Zstring can be a maximum of 100 characters and can contain carriage 
returns (ODH) . 



AL = 11H — Do a Soft-ICE command. 



This allows you to generate a Soft-ICE command from your program. This is 
used for all non-break point commands. To set Soft-ICE break points from 
your program see AL = 13H below. 



Input: DS:DX - > Zstring that contains a Soft-ICE 
command . 

[~jThe Zstring can be a maximum of 100 characters. Each Soft-ICE command in 
the string should end with a carriage return (ODH). 



D 
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AL = 12H — Get break point Information. 



Returns the break point number of the last break point set and the last 
break point that went off. 

[This is useful when setting break points from hardware control or doing 
hardware simulation. 

pReturns: DH - entry number of last break point that 



D 



went off 

DL - type of last break point that went off 
BH - entry number of last break point set 
BL - type of last break point set 



Crhe entry number is the same as is displayed in the BL command. 

The types are: - BPM (break point register types) 

1 - I/O 

2 - INT 

3 - BPX (int 3 style BP) 

4 - Reserved 

5 - Range 



D 



D 



AL = 13H — Set Soft-ICE break point. 



rUse this command to set Soft-ICE break points from program control. 
Input: DS:DX - pointer to break point structure 



D 
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Returns: ax = error code 

bx = break point number 



; Very little parameter value checking is done, but the following ; errors 

nare returned. 

L 0K EQU BP_TABLE_FULL EQU 3 MEM_L1M_ERR EQU 6 IO_LlM_ERR EQU 7 
RANGE L1M ERR EQU 9 DUP ERR EQU 16 /duplicate break point 



D 



; Break point structure 



; bp_entry 


struc 


jj;bp_type 


db ? 


;bp_addrl 


dd ? 


;bp_addr2 


dd ? 


;bp_addr3 


dd ? 


4 bpjmode 


db ? 


;bp mode2 


db ? 


[~|;bp_size 


db ? 


; bp_cnt 


db ? 


; bp_state 


db ? 


p;bp entry 


ends 


; The following break 



D 
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D 
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MEM_LOC equ ; Memory location 

break point (BPM) . 
MEM_RANGE equ 1 ; Memory range 

break point (BPR) . \ 
10 equ 3 ;I/0 break point 

(BPIO) . 

INT_BP equ 4 ; Interrupt break 

point (BPINT) . 
X_BP equ 5 /Execution break 

point (BPX) . 

; Here are the possible break point modes and sizes. 



D 
D 



; Break point modes 



J READ_MODE equ 01 

WRITE_MODE equ 02 

IJ EX_MODE equ 04 

; Break point sizes 



D 



BYT equ 

WRD equ 1 

DBL equ 3 



; The following paragraphs give information on how to fill the break point 
structure 



D 
D 
D 
D 
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D 

D 
0' 
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; for each break point type. 
; Setting memory location break points 



bp_type = MEM_LOC 
bp_addrl = address of break point 
bp_mode — one of following: 
READ_MODE 
WRITE_MODE 

EX_MODE or WRITE_MODE 
EX, MODE (execute break point) 
bp, size = one of following: 
BYT 
WRD 
DBL 

bp,cnt = Number of instances before 
breakpoint occurs 

; All unused fields should be 0. 

; Setting memory range break points 
bpjtype = MEM_RANGE 
bp_addrl - lower range limit 
bp_addr2 = upper range limit 
bp_mode = one of following: 
READ_MODE 
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WRITE_MODE 

READ_MODE or WRITE_MODE 

bp_cnt — Number of instances before breakpoint occurs 
; All unused fields should be 0. 
; Setting I/O break points 
bp_type = I/O 

word ptr bp_addrl = I/O address 
bp_mode = one of following: 
READ_MODE 
WRITE MODE 



n 

D 

D 
D 
D 
D 

D 

d 



READ_MODE or WRITE_MODE 
bp_cnt = Number of instances before 
breakpoint occurs 

; All unused fields should be 0. 

; Setting interrupt break points 
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bp_type = INT_BP 
bp,addrl = Interrupt # 
bp,addr2 = Optional value to check 
bp, mode - register to check 

- no value checking 

1 - check AL 

2 - check AH 

3 - check AX 

/Setting execution break points 
bp_type = X_BP 

bp,addrl = address of break point 
bp,addr2 = overlay number (0 = root) 



AL - 14H — Remove Soft-ICE break point. 
Input: BX = Break point number 



^Returns: BX = ??? when set 
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Page 40 is blank 
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